{
  "openapi": "3.1.0",
  "info": {
    "title": "TrackShip Tracking API",
    "description": "The TrackShip Tracking API lets you create, retrieve, and delete shipment trackers and list supported shipping providers. All authenticated requests must send the `trackship-api-key` and `app-name` headers. See the human documentation at https://docs.trackship.com/docs/tracking-api/ .",
    "version": "1.0.0",
    "contact": {
      "name": "TrackShip Support",
      "url": "https://docs.trackship.com/docs/tracking-api/"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.trackship.com/v1",
      "description": "TrackShip production API"
    }
  ],
  "externalDocs": {
    "description": "TrackShip Tracking API documentation",
    "url": "https://docs.trackship.com/docs/tracking-api/"
  },
  "tags": [
    { "name": "Shipments", "description": "Create, retrieve, and delete shipment trackers." },
    { "name": "Shipping providers", "description": "Reference data for supported carriers." }
  ],
  "security": [
    { "TrackShipApiKey": [], "AppName": [] }
  ],
  "paths": {
    "/shipment/create/": {
      "post": {
        "operationId": "createShipment",
        "summary": "Create a tracking",
        "description": "Create a shipment tracker. Returns the account's remaining tracker balance and plan.",
        "tags": ["Shipments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateShipmentRequest" },
              "example": {
                "tracking_number": "1Z4937W56728755212",
                "tracking_provider": "ups",
                "order_id": "13",
                "postal_code": "98012",
                "destination_country": "US"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tracker created (or a status message explaining why it could not be).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateShipmentResponse" },
                "example": {
                  "status": "ok",
                  "status_msg": "pending_trackship",
                  "trackers_balance": "98",
                  "user_plan": "Mini"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/InvalidRoute" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/shipment/get/": {
      "post": {
        "operationId": "getShipmentStatus",
        "summary": "Get a shipment status",
        "description": "Retrieve the current tracking status and event history of a shipment.",
        "tags": ["Shipments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/GetShipmentRequest" },
              "example": {
                "tracking_number": "6860010537552",
                "tracking_provider": "delhivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipment tracking data, or an error object when the tracking does not exist.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ShipmentStatusResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/InvalidRoute" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/shipment/by-order-id": {
      "post": {
        "operationId": "getShipmentsByOrderId",
        "summary": "Get shipments by order id",
        "description": "Retrieve the tracking status of all shipments associated with a specific order id.",
        "tags": ["Shipments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ByOrderIdRequest" },
              "example": { "order_id": "141" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A list of shipments for the order, or an error object when the order id is not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ByOrderIdResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/InvalidRoute" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/shipment/delete/": {
      "post": {
        "operationId": "deleteShipment",
        "summary": "Delete a shipment tracker",
        "description": "Delete a shipment tracker for the given tracking number, provider, and order id.",
        "tags": ["Shipments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DeleteShipmentRequest" },
              "example": {
                "tracking_number": "1Z4937W56728755212",
                "tracking_provider": "ups",
                "order_id": "10"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deletion result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DeleteShipmentResponse" },
                "examples": {
                  "success": { "value": { "status": "success", "message": "Shipment deleted successfully" } },
                  "error": { "value": { "status": "error", "message": "app name not found" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/InvalidRoute" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/shipping_carriers/supported": {
      "get": {
        "operationId": "getSupportedShippingProviders",
        "summary": "Get all shipping providers",
        "description": "List all shipping providers (carriers) supported by TrackShip. This endpoint does not require authentication.",
        "tags": ["Shipping providers"],
        "security": [],
        "responses": {
          "200": {
            "description": "The full list of supported shipping providers.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ShippingProvidersResponse" },
                "example": {
                  "success": true,
                  "data": [
                    { "label": "Australia Post", "slug": "australia-post" },
                    { "label": "CouriersPlease", "slug": "couriersplease" }
                  ]
                }
              }
            }
          },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "TrackShipApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "trackship-api-key",
        "description": "Your TrackShip API key. Found under Account Setting > API Key."
      },
      "AppName": {
        "type": "apiKey",
        "in": "header",
        "name": "app-name",
        "description": "Your app name. Found under Stores > settings > Webhook."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The requested parameter is missing (e.g. order id, tracking number, or shipping provider not found).",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "status": "error", "message": "Order id not found" }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized API access. Causes include `ssl_error` (store URL is not HTTPS) or `unauthorized` (invalid API key or the store does not exist).",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "status": "error", "message": "unauthorized" }
          }
        }
      },
      "InvalidRoute": {
        "description": "The API route does not exist. Check the URL and try again.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "status": "error", "message": "Invalid route" }
          }
        }
      },
      "ServerError": {
        "description": "The server encountered an unexpected condition that prevented it from fulfilling the request.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "status": "error", "message": "Internal Server Error" }
          }
        }
      }
    },
    "schemas": {
      "CreateShipmentRequest": {
        "type": "object",
        "required": ["tracking_number", "tracking_provider", "order_id"],
        "properties": {
          "tracking_number": { "type": "string", "description": "Tracking number for the package." },
          "tracking_provider": { "type": "string", "description": "Unique code of the tracking provider. See the shipping provider reference." },
          "order_id": { "type": "string", "description": "Respective order id." },
          "postal_code": { "type": "string", "description": "Postal code of the receiver's address. Required for some couriers, such as postnl-3s." },
          "destination_country": { "type": "string", "description": "Destination country of the receiver's address (e.g. NL). Required for some couriers, such as postnl-3s." }
        }
      },
      "CreateShipmentResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "description": "Response status (e.g. ok/error)." },
          "status_msg": { "type": "string", "description": "Status message explaining the state of the shipment (e.g. pending_trackship, ssl_error, Order id not found)." },
          "trackers_balance": { "type": "string", "description": "Available tracker balance of the TrackShip account." },
          "user_plan": { "type": "string", "description": "Active subscription plan of the TrackShip account (e.g. Free 50, Mini, Small)." }
        }
      },
      "GetShipmentRequest": {
        "type": "object",
        "required": ["tracking_number"],
        "properties": {
          "tracking_number": { "type": "string", "description": "Tracking number for the package." },
          "tracking_provider": { "type": "string", "description": "Unique code of the tracking provider for that tracking." }
        }
      },
      "ByOrderIdRequest": {
        "type": "object",
        "required": ["order_id"],
        "properties": {
          "order_id": { "type": "string", "description": "The unique id of the order." }
        }
      },
      "DeleteShipmentRequest": {
        "type": "object",
        "required": ["tracking_number", "tracking_provider", "order_id"],
        "properties": {
          "tracking_number": { "type": "string", "description": "Tracking number for the package." },
          "tracking_provider": { "type": "string", "description": "Unique code of the tracking provider for that tracking." },
          "order_id": { "type": "string", "description": "Respective order id." }
        }
      },
      "ShipmentStatusResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "description": "success or error." },
          "data": { "$ref": "#/components/schemas/ShipmentData" },
          "message": { "type": "string", "description": "Response message (present on error, e.g. \"tracking information is not exist\")." }
        }
      },
      "ByOrderIdResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "description": "success or error." },
          "data": {
            "type": "array",
            "description": "Shipment tracking data for every shipment on the order.",
            "items": { "$ref": "#/components/schemas/ShipmentData" }
          },
          "message": { "type": "string", "description": "Response message (present on error, e.g. \"Order ID not found\")." }
        }
      },
      "ShipmentData": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "tracking_number": { "type": "string" },
          "tracking_provider": { "type": "string" },
          "tracking_event_status": { "type": "string", "description": "Current tracking status (e.g. pre_transit, in_transit, delivered)." },
          "tracking_est_delivery_date": { "type": ["string", "null"] },
          "origin_country": { "type": ["string", "null"] },
          "destination_country": { "type": ["string", "null"] },
          "delivery_number": { "type": ["string", "null"] },
          "delivery_provider": { "type": ["string", "null"] },
          "shipping_service": { "type": ["string", "null"] },
          "last_event_time": { "type": ["string", "null"] },
          "events": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TrackingEvent" }
          },
          "destination_events": {
            "type": ["array", "null"],
            "items": { "$ref": "#/components/schemas/TrackingEvent" }
          }
        }
      },
      "TrackingEvent": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "description": "Object type, e.g. TrackingDetail." },
          "message": { "type": "string" },
          "description": { "type": "string" },
          "status": { "type": "string" },
          "status_detail": { "type": "string" },
          "datetime": { "type": "string" },
          "source": { "type": "string" },
          "tracking_location": { "$ref": "#/components/schemas/TrackingLocation" }
        }
      },
      "TrackingLocation": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "description": "Object type, e.g. TrackingLocation." },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "country": { "type": "string" },
          "zip": { "type": "string" }
        }
      },
      "DeleteShipmentResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "description": "success or error." },
          "message": { "type": "string", "description": "Response message." }
        }
      },
      "ShippingProvidersResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "description": "Whether the API response succeeded." },
          "data": {
            "type": "array",
            "description": "Supported shipping providers.",
            "items": { "$ref": "#/components/schemas/ShippingProvider" }
          }
        }
      },
      "ShippingProvider": {
        "type": "object",
        "properties": {
          "label": { "type": "string", "description": "Human-readable carrier name (e.g. Australia Post)." },
          "slug": { "type": "string", "description": "Unique provider code used as tracking_provider (e.g. australia-post)." }
        }
      },
      "Error": {
        "type": "object",
        "description": "Standard error object returned by the TrackShip API.",
        "properties": {
          "status": { "type": "string", "description": "Always \"error\" for error responses." },
          "message": { "type": "string", "description": "Human-readable error message." }
        }
      }
    }
  }
}