openapi: 3.0.0 info: title: WhereParcel API version: 2.0.0 description: Real-time parcel tracking API for 64+ carriers contact: name: WhereParcel Support email: support@whereparcel.com url: https://whereparcel.com servers: - url: https://api.whereparcel.com/v2 description: Production components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Format: Bearer {apiKey}:{secretKey}' FirebaseAuth: type: http scheme: bearer bearerFormat: JWT description: Firebase ID Token schemas: RegisterWebhookRequest: description: |- Unified webhook registration request (Bulk + Recurring support) Usage patterns: 1. Bulk + Recurring: { webhookEndpointId, trackingItems: [...], recurring: true } 2. Bulk + One-time: { trackingItems: [...], recurring: false, webhookEndpointId?: ... } 3. Bulk + One-time (no webhook): { trackingItems: [...], recurring: false } type: object properties: trackingItems: description: Tracking items (up to 100) type: array items: type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string postalCode: type: string phoneNumber: type: string required: - carrier - trackingNumber recurring: description: |- Tracking mode (optional, default: false) - false: Query once only (default, safe) → webhookEndpointId optional - true: Continuous monitoring (explicit request required) → webhookEndpointId required type: boolean webhookEndpointId: description: |- Pre-registered Webhook Endpoint ID - Required when recurring: true (validated by middleware) - Optional when recurring: false - If provided, sends POST on completion; if omitted, no notification sent - Must register a Webhook Endpoint first type: string required: - trackingItems RegisterWebhookRecurringResponse: description: |- Recurring mode response (subscription) Returned when recurring: true type: object properties: mode: type: string const: recurring requestId: type: string trackingItemCount: type: number webhookEndpointId: type: string createdAt: type: string required: - createdAt - mode - requestId - trackingItemCount - webhookEndpointId RegisterWebhookOneTimeResponse: description: |- One-time mode response Returned when recurring: false type: object properties: mode: type: string const: one-time requestId: type: string webhookEndpointId: type: string webhookDelivered: type: boolean progress: type: object properties: total: type: number completed: type: number succeeded: type: number failed: type: number percentage: type: number required: - completed - failed - percentage - succeeded - total results: type: array items: $ref: '#/components/schemas/TrackingResultItem' required: - mode - progress - requestId - results - webhookDelivered ListTrackingRequestsResponse: description: List tracking requests response type: object properties: requestId: type: string trackingItemCount: type: number trackingItems: type: array items: $ref: '#/components/schemas/TrackingItemSummary' recurring: type: boolean webhookEndpointId: type: string isActive: type: boolean progress: type: object properties: total: type: number completed: type: number succeeded: type: number failed: type: number percentage: type: number required: - completed - failed - percentage - succeeded - total createdAt: type: string updatedAt: type: string completedAt: type: string required: - createdAt - isActive - recurring - requestId - trackingItemCount - trackingItems - updatedAt DeleteTrackingRequestResponse: description: Delete tracking request response type: object properties: deleted: type: boolean requestId: type: string message: type: string required: - deleted - message - requestId GetWebhookSubscriptionResponse: description: Single webhook subscription response type: object properties: success: type: boolean data: description: |- Unified tracking request (Webhook Subscription + Bulk Job) - recurring: true → Continuous monitoring (polling) - recurring: false → Query once only $ref: '#/components/schemas/TrackingRequestDocument' error: type: object properties: code: type: string message: type: string required: - code - message required: - success ListTrackingChangesResponse: description: Tracking change history list response type: object properties: requestId: type: string changes: type: array items: $ref: '#/components/schemas/TrackingChangeItem' pagination: type: object properties: limit: type: number hasMore: type: boolean required: - hasMore - limit required: - changes - pagination - requestId GetTrackingChangeResponse: description: Tracking change history detail response type: object properties: changeId: type: string requestId: type: string timestamp: type: string changedItemCount: type: number changedItems: type: array items: $ref: '#/components/schemas/TrackingChangeDetailItem' required: - changeId - changedItemCount - changedItems - requestId - timestamp SearchWebhookResultByTrackingResponse: type: object properties: source: type: string const: bulk data: anyOf: - $ref: '#/components/schemas/TrackingData' - type: 'null' status: type: string nullable: true count: type: number registrations: type: array items: $ref: '#/components/schemas/RegistrationInfo' required: - count - data - registrations - source - status SearchWebhookResultByClientIdResponse: type: object properties: source: type: string const: bulk data: type: array items: $ref: '#/components/schemas/SearchResultItem' registrations: type: array items: $ref: '#/components/schemas/RegistrationInfo' required: - data - registrations - source SearchWebhookResultsBatchRequest: description: Batch search request type: object properties: trackingItems: type: array items: anyOf: - type: object properties: carrier: type: string trackingNumber: type: string required: - carrier - trackingNumber - type: object properties: clientId: type: string required: - clientId required: - trackingItems SearchWebhookResultsBatchResponse: type: object properties: results: $ref: >- #/definitions/Record%3Cstring%2C%7Bsource%3A%22none%22%7C%22bulk%22%7C%22cache%22%3Bdata%3ATrackingData%7CTrackingData%5B%5D%7Cnull%3Bstatus%3F%3Astring%7Cnull%7Cundefined%3BjobId%3F%3Astring%7Cundefined%3BcreatedAt%3F%3Astring%7Cundefined%3B%7D%3E required: - results ApiError: description: API error (common) type: object properties: code: type: string message: type: string required: - code - message TrackingResultItem: description: Tracking result item (for webhook/API responses) type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string status: enum: - failed - success type: string data: description: |- Tracking data (full delivery information) Contains complete delivery information for a specific tracking number. All fields are converted to WhereParcel standard format. $ref: '#/components/schemas/TrackingData' error: description: API error (common) $ref: '#/components/schemas/ApiError' required: - carrier - status - trackingNumber TrackingItemPayload: description: Tracking item payload (for webhook payload) type: object properties: carrier: $ref: '#/components/schemas/CarrierInfo' trackingNumber: type: string status: enum: - failed - success type: string currentStatus: type: string trackingData: description: |- Tracking data (full delivery information) Contains complete delivery information for a specific tracking number. All fields are converted to WhereParcel standard format. $ref: '#/components/schemas/TrackingData' error: description: API error (common) $ref: '#/components/schemas/ApiError' required: - carrier - status - trackingNumber TrackingItemSummary: description: Tracking item summary (for list queries) type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string latestStatus: type: string required: - carrier - trackingNumber TrackingItemStatus: description: Tracking item status (for TrackingRequestDocument) type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string postalCode: type: string phoneNumber: type: string latestStatus: type: string status: enum: - failed - pending - processing - retrying - success type: string trackingData: description: |- Tracking data (full delivery information) Contains complete delivery information for a specific tracking number. All fields are converted to WhereParcel standard format. $ref: '#/components/schemas/TrackingData' error: description: API error (common) $ref: '#/components/schemas/ApiError' required: - carrier - trackingNumber TrackingChangeItem: description: Change history list item (summary) type: object properties: changeId: type: string timestamp: type: string changedItemCount: type: number preview: type: object properties: trackingNumbers: type: array items: type: string required: - trackingNumbers required: - changeId - changedItemCount - preview - timestamp TrackingChangeDetailItem: description: Individual changed item within a change record type: object properties: carrier: type: string trackingNumber: type: string previousStatus: type: string currentStatus: type: string trackingData: $ref: '#/components/schemas/TrackingData' required: - carrier - currentStatus - trackingData - trackingNumber SearchResultItem: description: Search result item (for clientId search) type: object properties: trackingKey: type: string carrier: type: string trackingNumber: type: string clientId: type: string status: type: string result: description: |- Tracking data (full delivery information) Contains complete delivery information for a specific tracking number. All fields are converted to WhereParcel standard format. $ref: '#/components/schemas/TrackingData' error: description: API error (common) $ref: '#/components/schemas/ApiError' required: - carrier - status - trackingKey - trackingNumber RegistrationInfo: description: Registration info (for search results) type: object properties: jobId: type: string count: type: number status: type: string createdAt: type: string required: - count - createdAt - jobId CreateWebhookEndpointRequest: type: object properties: name: type: string url: type: string secret: type: string description: type: string required: - name - url CreateWebhookEndpointResponse: type: object properties: success: type: boolean data: type: object properties: endpointId: type: string name: type: string url: type: string secret: type: string description: type: string isActive: type: boolean createdAt: type: string required: - createdAt - endpointId - isActive - name - secret - url error: type: object properties: code: type: string message: type: string required: - code - message required: - success UpdateWebhookEndpointRequest: type: object properties: name: type: string url: type: string description: type: string isActive: type: boolean UpdateWebhookEndpointResponse: type: object properties: success: type: boolean data: type: object properties: endpointId: type: string name: type: string url: type: string description: type: string isActive: type: boolean updatedAt: type: string required: - endpointId - isActive - name - updatedAt - url error: type: object properties: code: type: string message: type: string required: - code - message required: - success DeleteWebhookEndpointResponse: description: Delete webhook endpoint response type: object properties: success: type: boolean message: type: string required: - message - success ListWebhookEndpointsResponse: type: object properties: success: type: boolean data: type: array items: type: object properties: endpointId: type: string name: type: string url: type: string description: type: string isActive: type: boolean createdAt: type: string updatedAt: type: string required: - createdAt - endpointId - isActive - name - updatedAt - url error: type: object properties: code: type: string message: type: string required: - code - message required: - success WebhookEndpoint: type: object properties: endpointId: type: string userId: type: string apiKeyId: type: string name: type: string url: type: string secret: type: string description: type: string isActive: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - apiKeyId - createdAt - endpointId - isActive - name - secret - updatedAt - url - userId BulkTrackingRequest: description: Bulk tracking request type: object properties: trackingItems: type: array items: $ref: '#/components/schemas/TrackingRequest' required: - trackingItems BulkTrackingResponse: description: |- Bulk tracking response Responds with HTTP 200 OK, with success/failure status for each item within the results array. type: object properties: success: type: boolean const: true results: type: array items: $ref: '#/components/schemas/TrackingResult' summary: type: object properties: total: type: number success: type: number failed: type: number usageIncremented: type: number duplicates: type: number required: - failed - success - total - usageIncremented requestLimit: description: |- API request limit information Per-second request limit applied to all API endpoints (server protection) $ref: '#/components/schemas/RequestLimit' trackingQuota: description: |- Tracking usage quota information Billing usage applied only to the /track endpoint (per minute/day/month) $ref: '#/components/schemas/TrackingQuota' processingTime: type: number coldStart: type: boolean required: - results - success - summary TrackingResponse: type: object properties: success: type: boolean const: true result: $ref: '#/components/schemas/TrackingResult' requestLimit: description: |- API request limit information Per-second request limit applied to all API endpoints (server protection) $ref: '#/components/schemas/RequestLimit' trackingQuota: description: |- Tracking usage quota information Billing usage applied only to the /track endpoint (per minute/day/month) $ref: '#/components/schemas/TrackingQuota' processingTime: type: number coldStart: type: boolean required: - result - success TrackingData: description: |- Tracking data (full delivery information) Contains complete delivery information for a specific tracking number. All fields are converted to WhereParcel standard format. type: object properties: deliveryStatus: $ref: '#/components/schemas/TrackingStatus' description: |- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. One of 8 standard statuses defined in the TrackingStatus type. Note: Named deliveryStatus to distinguish from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: description: |- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, this represents the actual delivery time. Note: The meaning of this field varies by status: - status is "delivered": Actual delivery completion time - status is other: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide estimated delivery dates. type: string events: description: |- Delivery event list Chronologically sorted delivery history. The most recent event is at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) type: array items: $ref: '#/components/schemas/TrackingEvent' from: description: |- Sender information (optional) Location information where the parcel was shipped from. Names may be masked for privacy protection. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (business: original) - address: "Gangnam-gu, Seoul", "Tokyo, Japan" Note: Some carriers may not provide sender information. type: object properties: name: type: string address: type: string to: description: |- Recipient information (optional) Location information where the parcel will be delivered. Names and detailed addresses may be masked for privacy protection. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (business: original) - address: "Seocho-gu, Seoul" (detailed address excluded) Note: Some carriers may not provide recipient information. type: object properties: name: type: string address: type: string signedBy: description: |- Signature information (optional) The name of the person who signed upon delivery completion. Primarily provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended deliveries (e.g., left at door) will be null. type: string weight: description: |- Weight information (optional) The weight of the parcel. Primarily provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic carriers do not provide weight information. type: object properties: value: type: number unit: enum: - g - kg - lb type: string required: - unit - value deliveryInstructions: description: |- Delivery instructions (optional) Customer-requested delivery instructions. Examples: - "Leave at security desk if absent" - "Leave at front door" - "Call before delivery" Note: Most carriers do not provide this. type: string lastUpdated: description: |- Last updated date/time (ISO 8601 format) The time when WhereParcel retrieved data from the carrier. Used to determine the freshness of cached data. Example: - "2026-01-30T15:30:00Z" Note: This is not the carrier's last update time. type: string required: - deliveryStatus - events - lastUpdated TrackingEvent: description: |- Delivery event (individual tracking record) Represents each step of the parcel's journey. Sorted chronologically to track delivery history. type: object properties: timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. Without this flag a filled-in noon is indistinguishable from a real scan at noon, which is why several events on the same date can look like they share one timestamp. type: boolean timestamp: description: |- Event timestamp (ISO 8601 format) Standardized time by WhereParcel. Converts various carrier time formats to ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korean carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" type: string status: $ref: '#/components/schemas/TrackingStatus' description: |- Delivery status (WhereParcel standardized) Standardized value of the TrackingStatus type. Converts various carrier status codes into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan Post "配達完了" → "delivered" location: description: |- Location information (WhereParcel standardized, optional) The physical location where the event occurred. Standardizes different carrier location formats as much as possible. Examples: - Korea: "Gangnam-gu, Teheran-ro, Seoul", "Buk-gu Logistics Center, Busan" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. type: string description: description: |- Event description (WhereParcel standardized) Detailed description of the event. Translated to the user's language when possible. Examples: - Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by JOHN DOE" - USPS: "Out for Delivery" - DHL: "Customs clearance completed" type: string rawStatus: description: |- Carrier original status code (optional) Preserves the original status code/text as displayed by the carrier. Provided so customers can compare with the carrier's official website. Examples: - UPS: "M" (Manifest), "I" (In Transit), "D" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official website. type: string rawDescription: description: |- Carrier original description (optional) Preserves the original event description as displayed by the carrier. Unlike description, provided as-is without language conversion or standardization. Examples: - UPS: "Your package was delivered. Signed by: JOHN" - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - FedEx: "Delivered. Left at front door. Signature Service not requested." - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official website. type: string required: - description - status - timestamp TrackingRequest: description: |- Tracking request item Each item in the trackingItems array. Some carriers (e.g., GLS Germany) require additional fields such as postalCode. Check carrier requirements at GET /v2/carriers/{countryCode}. type: object properties: carrier: description: Carrier code (e.g., 'kr.cj', 'us.fedex', 'de.gls') type: string trackingNumber: description: Tracking number type: string clientId: description: Client tracking ID (returned as-is in the response) type: string postalCode: description: Postal code (required/optional for some carriers, e.g., GLS Germany) type: string phoneNumber: description: Phone number (required/optional for some carriers) type: string required: - carrier - trackingNumber TrackingResult: description: |- Tracking result (Discriminated Union) Both single and bulk queries use this type for complete consistency. anyOf: - $ref: '#/components/schemas/TrackingSuccessResult' - $ref: '#/components/schemas/TrackingErrorResult' TrackingHint: description: |- Additional input field hint (Result level) When a carrier has optional fields and they are not provided, this hint information is included in the response. Note: Located at Result level, not TrackingData level. (Prevents cache/webhook payload contamination) type: object properties: type: description: Hint type (always 'additional_field_available') type: string const: additional_field_available fieldName: description: Additional input field name (e.g., 'postalCode', 'phoneNumber') type: string message: description: Hint message type: string required: - fieldName - message - type CreateBulkJobRequest: description: Create bulk job request type: object properties: items: type: array items: type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string required: - carrier - trackingNumber webhook: type: object properties: endpointId: type: string required: - endpointId required: - items CreateBulkJobResponse: description: Create bulk job response type: object properties: success: type: boolean data: type: object properties: jobId: type: string status: $ref: '#/components/schemas/BulkJobStatus' itemCount: type: number statusUrl: type: string webhookUrl: type: string estimatedCompletionTime: type: string required: - itemCount - jobId - status - statusUrl error: type: object properties: code: type: string message: type: string required: - code - message required: - success GetBulkJobStatusResponse: description: |- Bulk job status response (matches actual implementation) GET /v2/webhooks/results/:jobId type: object properties: jobId: type: string status: $ref: '#/components/schemas/BulkJobStatus' progress: type: object properties: total: type: number completed: type: number succeeded: type: number failed: type: number percentage: type: number required: - completed - failed - percentage - succeeded - total tasks: $ref: '#/components/schemas/Record%3Cstring%2CBulkJobTask%3E' createdAt: type: string updatedAt: type: string completedAt: type: string required: - createdAt - jobId - progress - status - tasks - updatedAt ListCarriersResponse: description: |- GET /v2/carriers List supported carriers response type: object properties: success: type: boolean data: type: array items: type: string required: - data - success ListCountriesResponse: description: |- GET /v2/countries List supported countries response type: object properties: success: type: boolean data: type: array items: type: string required: - data - success GetCarriersByCountryResponse: description: |- GET /v2/carriers/{countryCode} Carriers by country response type: object properties: success: type: boolean data: type: array items: type: string required: - data - success GetCarriersByRegionResponse: description: |- GET /v2/carriers/{countryCode}/{region} Carriers by region response type: object properties: success: type: boolean data: type: array items: type: string required: - data - success ErrorInfo: description: Error details included in API error responses type: object properties: code: $ref: '#/components/schemas/ApiErrorCode' description: Error code (for programmatic handling) message: description: Human-readable error message type: string retryAfter: description: Wait time in seconds before retrying (when rate limit exceeded) type: number required: - code - message ApiErrorResponse: description: |- API error response All endpoint error responses follow this format. type: object properties: success: description: Always `false` type: boolean const: false error: $ref: '#/components/schemas/ErrorInfo' description: Error details invalidItems: description: List of validation failed items (in collect-all-errors response) type: array items: $ref: '#/components/schemas/ValidationErrorItem' required: - error - success TrackingStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (standardized value) The standard delivery status defined by WhereParcel. The various status codes of all carriers are converted into one of these 8 values. TrackingSuccessResult: type: object properties: carrier: type: string description: Carrier code trackingNumber: type: string description: Tracking number clientId: type: string description: Client tracking ID (the value provided at request time) data: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: |- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: |- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: |- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: Tracking result data billable: type: boolean description: Whether a charge is applied (true on Provider call, false on cache hit) cached: type: boolean description: Whether it was a cache hit duplicate: type: boolean description: Whether it is a duplicate within the same request hints: type: array items: type: object properties: type: type: string const: additional_field_available description: Notice type (always 'additional_field_available') fieldName: type: string description: Additional input field name (e.g., 'postalCode', 'phoneNumber') message: type: string description: Notice message required: - type - fieldName - message additionalProperties: false description: >- Additional input field notice (Result level) Notice information included in the response when a carrier that has an optional field did not provide that field. Note: Located at the Result level, not TrackingData. (Prevents cache/webhook payload contamination) description: Additional input field notice (when an optional field is not provided) status: type: string const: success required: - billable - cached - carrier - data - status - trackingNumber additionalProperties: false description: |- Tracking result (success) The type returned upon a successful Provider call. TrackingErrorResult: type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string status: type: string const: error error: type: object properties: code: type: string enum: - UNAUTHORIZED - AUTH_MISSING_API_KEY - AUTH_INVALID_CREDENTIALS - AUTH_INVALID_TOKEN - TOKEN_EXPIRED - TOKEN_REVOKED - KEY_INACTIVE - FORBIDDEN - RATE_LIMIT_EXCEEDED - MONTHLY_LIMIT_EXCEEDED - INVALID_REQUEST - REQUEST_INVALID_FORMAT - REQUEST_INVALID_CARRIER - REQUEST_INVALID_TRACKING_NUMBER - REQUEST_INVALID_CLIENT_ID - REQUEST_VALIDATION_FAILED - TRACKING_NOT_FOUND - INVALID_TRACKING_NUMBER - NOT_FOUND - DUPLICATE_URL - ENDPOINT_NOT_FOUND - ENDPOINT_INACTIVE - EMAIL_ALREADY_REGISTERED - CODE_EXPIRED - MAX_ATTEMPTS_EXCEEDED - INVALID_CODE - INVALID_TOKEN - EMAIL_MISMATCH - API_KEY_LIMIT_EXCEEDED - INVALID_WEBHOOK_URL - INVALID_DATE - INVALID_BODY - POSTAL_CODE_REQUIRED - POSTAL_CODE_INVALID_FORMAT - PHONE_NUMBER_REQUIRED - PHONE_NUMBER_INVALID_FORMAT - INTERNAL_ERROR description: Error code (for programmatic handling) message: type: string description: Human-readable error message retryAfter: type: number description: Wait time until retry when the rate limit is exceeded (seconds) required: - code - message additionalProperties: false description: Error detail information included in the API error response billable: type: boolean cached: type: boolean duplicate: type: boolean required: - carrier - trackingNumber - status - error - billable - cached additionalProperties: false description: |- Tracking result (failure) The type returned upon a failed Provider call. (e.g., tracking number not found, carrier API error, etc.) RequestLimit: type: object properties: second: type: string required: - second additionalProperties: false description: API rate limit information. The per-second request limit applied to all API endpoints (server protection) TrackingQuota: type: object properties: minute: type: string day: type: string month: type: string required: - minute - day - month additionalProperties: false description: Parcel tracking usage information. Billing usage applied only to the /track endpoint (per minute/day/month) BulkJobStatus: type: string enum: - processing - completed - failed description: Bulk Job status WebhookEvent: type: string enum: - status.changed - status.delivered - first.tracked - tracking.completed - tracking.failed - bulk.completed WebhookPayload: anyOf: - type: object properties: trackingNumber: type: string carrier: type: object properties: code: type: string description: |- Carrier code A unique identifier defined by WhereParcel. Format: {countryCode}.{carrierName} Examples: - 'kr.post' (South Korea, Korea Post) - 'kr.cj' (CJ Logistics) - 'us.fedex' (FedEx) - 'us.usps' (USPS) - 'intl.dhl' (DHL international shipping) name: anyOf: - type: string - type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support description: |- Carrier name A single-language string or a multilingual object. Examples: - "Korea Post" (string) - { ko: "Korea Post Parcel", en: "Korea Post" } (multilingual) serviceScope: type: string enum: - national - international description: |- Service scope The delivery scope provided by the carrier. - 'national': Domestic delivery only (e.g., South Korea → South Korea) - 'international': International delivery (e.g., South Korea → USA) country: type: string description: |- Country code (ISO 3166-1 alpha-2) The country where the carrier's headquarters is located, or its main country of operation. Examples: - 'KR': South Korea - 'US': USA - 'JP': Japan - 'CN': China - 'DE': Germany - 'INTL': International shipping only (country cannot be specified) region: type: string description: |- Region code (optional) Used when carriers differ by region, as in the USA. Examples: - 'CA': California - 'TX': Texas - 'NY': New York Note: Most countries do not use this field. trackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: |- Tracking number pattern (optional) A description of the valid tracking number format. It can be used for client-side validation. Examples: - { regex: '^[0-9]{10,13}$', description: '10-13 digit number' } - { regex: '^[A-Z]{2}[0-9]{9}[A-Z]{2}$', description: '2 letters + 9 digits + 2 letters' } postalCode: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: |- Postal code field requirement (for public API) Only requirement is exposed. validation/message are managed in CarrierMetadata. phoneNumber: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: Phone number field requirement (for public API) required: - code - name - serviceScope - country additionalProperties: false description: >- Carrier information (for public API) Carrier metadata provided to customers. It does not include internal implementation information (providerType, developmentStatus). previousStatus: type: string currentStatus: type: string trackingData: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: >- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: >- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: >- Tracking data (full delivery information) Contains the full delivery information for a specific tracking number. All fields are converted to and provided in the WhereParcel standard format. timestamp: type: string required: - trackingNumber - carrier - currentStatus - trackingData - timestamp additionalProperties: false description: Tracking webhook Payload (subscription type) - type: object properties: requestId: type: string jobId: type: string trackingItemCount: type: number successCount: type: number failureCount: type: number results: type: array items: type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string status: type: string enum: - success - failed data: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: >- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: >- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: >- Tracking data (full delivery information) Contains the full delivery information for a specific tracking number. All fields are converted to and provided in the WhereParcel standard format. error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false description: API error (common) required: - carrier - trackingNumber - status additionalProperties: false description: Tracking result item (for webhook/API response) timestamp: type: string required: - requestId - trackingItemCount - successCount - failureCount - results - timestamp additionalProperties: false description: Bulk tracking webhook Payload (one-time) - type: object properties: requestId: type: string trackingItems: type: array items: type: object properties: carrier: type: object properties: code: type: string description: |- Carrier code A unique identifier defined by WhereParcel. Format: {countryCode}.{carrierName} Examples: - 'kr.post' (South Korea, Korea Post) - 'kr.cj' (CJ Logistics) - 'us.fedex' (FedEx) - 'us.usps' (USPS) - 'intl.dhl' (DHL international shipping) name: anyOf: - type: string - type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support description: |- Carrier name A single-language string or a multilingual object. Examples: - "Korea Post" (string) - { ko: "Korea Post Parcel", en: "Korea Post" } (multilingual) serviceScope: type: string enum: - national - international description: |- Service scope The delivery scope provided by the carrier. - 'national': Domestic delivery only (e.g., South Korea → South Korea) - 'international': International delivery (e.g., South Korea → USA) country: type: string description: |- Country code (ISO 3166-1 alpha-2) The country where the carrier's headquarters is located, or its main country of operation. Examples: - 'KR': South Korea - 'US': USA - 'JP': Japan - 'CN': China - 'DE': Germany - 'INTL': International shipping only (country cannot be specified) region: type: string description: |- Region code (optional) Used when carriers differ by region, as in the USA. Examples: - 'CA': California - 'TX': Texas - 'NY': New York Note: Most countries do not use this field. trackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: |- Tracking number pattern (optional) A description of the valid tracking number format. It can be used for client-side validation. Examples: - { regex: '^[0-9]{10,13}$', description: '10-13 digit number' } - { regex: '^[A-Z]{2}[0-9]{9}[A-Z]{2}$', description: '2 letters + 9 digits + 2 letters' } postalCode: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: |- Postal code field requirement (for public API) Only requirement is exposed. validation/message are managed in CarrierMetadata. phoneNumber: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: Phone number field requirement (for public API) required: - code - name - serviceScope - country additionalProperties: false description: >- Carrier information (for public API) Carrier metadata provided to customers. It does not include internal implementation information (providerType, developmentStatus). trackingNumber: type: string status: type: string enum: - success - failed currentStatus: type: string trackingData: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: >- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: >- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: >- Tracking data (full delivery information) Contains the full delivery information for a specific tracking number. All fields are converted to and provided in the WhereParcel standard format. error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false description: API error (common) required: - carrier - trackingNumber - status additionalProperties: false description: Tracking entry item (for webhook Payload) timestamp: type: string required: - requestId - trackingItems - timestamp additionalProperties: false description: |- Tracking entry array webhook Payload - first.tracked: First tracking completed (all items) - tracking.completed: Tracking completed (all items, including success/failure) - status.changed: Status changed (changed items only) - type: object properties: trackingNumber: type: string carrier: type: object properties: code: type: string description: |- Carrier code A unique identifier defined by WhereParcel. Format: {countryCode}.{carrierName} Examples: - 'kr.post' (South Korea, Korea Post) - 'kr.cj' (CJ Logistics) - 'us.fedex' (FedEx) - 'us.usps' (USPS) - 'intl.dhl' (DHL international shipping) name: anyOf: - type: string - type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support description: |- Carrier name A single-language string or a multilingual object. Examples: - "Korea Post" (string) - { ko: "Korea Post Parcel", en: "Korea Post" } (multilingual) serviceScope: type: string enum: - national - international description: |- Service scope The delivery scope provided by the carrier. - 'national': Domestic delivery only (e.g., South Korea → South Korea) - 'international': International delivery (e.g., South Korea → USA) country: type: string description: |- Country code (ISO 3166-1 alpha-2) The country where the carrier's headquarters is located, or its main country of operation. Examples: - 'KR': South Korea - 'US': USA - 'JP': Japan - 'CN': China - 'DE': Germany - 'INTL': International shipping only (country cannot be specified) region: type: string description: |- Region code (optional) Used when carriers differ by region, as in the USA. Examples: - 'CA': California - 'TX': Texas - 'NY': New York Note: Most countries do not use this field. trackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: |- Tracking number pattern (optional) A description of the valid tracking number format. It can be used for client-side validation. Examples: - { regex: '^[0-9]{10,13}$', description: '10-13 digit number' } - { regex: '^[A-Z]{2}[0-9]{9}[A-Z]{2}$', description: '2 letters + 9 digits + 2 letters' } postalCode: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: |- Postal code field requirement (for public API) Only requirement is exposed. validation/message are managed in CarrierMetadata. phoneNumber: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: Phone number field requirement (for public API) required: - code - name - serviceScope - country additionalProperties: false description: >- Carrier information (for public API) Carrier metadata provided to customers. It does not include internal implementation information (providerType, developmentStatus). error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false timestamp: type: string required: - trackingNumber - carrier - error - timestamp additionalProperties: false description: |- Tracking failure webhook Payload - tracking.failed: Individual item tracking failed description: Webhook Payload (Union Type) TrackingWebhookPayload: type: object properties: trackingNumber: type: string carrier: type: object properties: code: type: string description: |- Carrier code A unique identifier defined by WhereParcel. Format: {countryCode}.{carrierName} Examples: - 'kr.post' (South Korea, Korea Post) - 'kr.cj' (CJ Logistics) - 'us.fedex' (FedEx) - 'us.usps' (USPS) - 'intl.dhl' (DHL international shipping) name: anyOf: - type: string - type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support description: |- Carrier name A single-language string or a multilingual object. Examples: - "Korea Post" (string) - { ko: "Korea Post Parcel", en: "Korea Post" } (multilingual) serviceScope: type: string enum: - national - international description: |- Service scope The delivery scope provided by the carrier. - 'national': Domestic delivery only (e.g., South Korea → South Korea) - 'international': International delivery (e.g., South Korea → USA) country: type: string description: |- Country code (ISO 3166-1 alpha-2) The country where the carrier's headquarters is located, or its main country of operation. Examples: - 'KR': South Korea - 'US': USA - 'JP': Japan - 'CN': China - 'DE': Germany - 'INTL': International shipping only (country cannot be specified) region: type: string description: |- Region code (optional) Used when carriers differ by region, as in the USA. Examples: - 'CA': California - 'TX': Texas - 'NY': New York Note: Most countries do not use this field. trackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: |- Tracking number pattern (optional) A description of the valid tracking number format. It can be used for client-side validation. Examples: - { regex: '^[0-9]{10,13}$', description: '10-13 digit number' } - { regex: '^[A-Z]{2}[0-9]{9}[A-Z]{2}$', description: '2 letters + 9 digits + 2 letters' } postalCode: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: |- Postal code field requirement (for public API) Only requirement is exposed. validation/message are managed in CarrierMetadata. phoneNumber: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: Phone number field requirement (for public API) required: - code - name - serviceScope - country additionalProperties: false description: >- Carrier information (for public API) Carrier metadata provided to customers. It does not include internal implementation information (providerType, developmentStatus). previousStatus: type: string currentStatus: type: string trackingData: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: |- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: |- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: |- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: >- Tracking data (full delivery information) Contains the full delivery information for a specific tracking number. All fields are converted to and provided in the WhereParcel standard format. timestamp: type: string required: - trackingNumber - carrier - currentStatus - trackingData - timestamp additionalProperties: false description: Tracking webhook Payload (subscription type) BulkTrackingWebhookPayload: type: object properties: requestId: type: string jobId: type: string trackingItemCount: type: number successCount: type: number failureCount: type: number results: type: array items: type: object properties: carrier: type: string trackingNumber: type: string clientId: type: string status: type: string enum: - success - failed data: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: >- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: >- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: >- Tracking data (full delivery information) Contains the full delivery information for a specific tracking number. All fields are converted to and provided in the WhereParcel standard format. error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false description: API error (common) required: - carrier - trackingNumber - status additionalProperties: false description: Tracking result item (for webhook/API response) timestamp: type: string required: - requestId - trackingItemCount - successCount - failureCount - results - timestamp additionalProperties: false description: Bulk tracking webhook Payload (one-time) TrackingItemsWebhookPayload: type: object properties: requestId: type: string trackingItems: type: array items: type: object properties: carrier: type: object properties: code: type: string description: |- Carrier code A unique identifier defined by WhereParcel. Format: {countryCode}.{carrierName} Examples: - 'kr.post' (South Korea, Korea Post) - 'kr.cj' (CJ Logistics) - 'us.fedex' (FedEx) - 'us.usps' (USPS) - 'intl.dhl' (DHL international shipping) name: anyOf: - type: string - type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support description: |- Carrier name A single-language string or a multilingual object. Examples: - "Korea Post" (string) - { ko: "Korea Post Parcel", en: "Korea Post" } (multilingual) serviceScope: type: string enum: - national - international description: |- Service scope The delivery scope provided by the carrier. - 'national': Domestic delivery only (e.g., South Korea → South Korea) - 'international': International delivery (e.g., South Korea → USA) country: type: string description: |- Country code (ISO 3166-1 alpha-2) The country where the carrier's headquarters is located, or its main country of operation. Examples: - 'KR': South Korea - 'US': USA - 'JP': Japan - 'CN': China - 'DE': Germany - 'INTL': International shipping only (country cannot be specified) region: type: string description: |- Region code (optional) Used when carriers differ by region, as in the USA. Examples: - 'CA': California - 'TX': Texas - 'NY': New York Note: Most countries do not use this field. trackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: |- Tracking number pattern (optional) A description of the valid tracking number format. It can be used for client-side validation. Examples: - { regex: '^[0-9]{10,13}$', description: '10-13 digit number' } - { regex: '^[A-Z]{2}[0-9]{9}[A-Z]{2}$', description: '2 letters + 9 digits + 2 letters' } postalCode: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: |- Postal code field requirement (for public API) Only requirement is exposed. validation/message are managed in CarrierMetadata. phoneNumber: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: Phone number field requirement (for public API) required: - code - name - serviceScope - country additionalProperties: false description: >- Carrier information (for public API) Carrier metadata provided to customers. It does not include internal implementation information (providerType, developmentStatus). trackingNumber: type: string status: type: string enum: - success - failed currentStatus: type: string trackingData: type: object properties: deliveryStatus: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Current delivery status (WhereParcel standardized) Represents the status of the most recent event. It is one of the 8 standard statuses of the TrackingStatus type. Note: It is named deliveryStatus to distinguish it from result.status. - result.status: API call result ("success" | "error") - deliveryStatus: Actual delivery status ("delivered" | "in_transit" | ...) estimatedDelivery: type: string description: >- Estimated delivery date/time (optional, ISO 8601 format) The estimated delivery date/time provided by the carrier. When delivery is complete, it represents the actual delivery completion time. Note: The meaning of this field varies depending on status: - status is "delivered": Actual delivery completion time - status is otherwise: Estimated delivery date/time (subject to change) Examples: - "2026-01-30T18:00:00+09:00" (Korea timezone) - "2026-01-30T14:00:00-05:00" (US Eastern timezone) Note: Some carriers may not provide an estimated delivery date/time. events: type: array items: type: object properties: timestamp: type: string description: >- Event occurrence time (ISO 8601 format) The time standardized by WhereParcel. It converts the differing time formats of each carrier into ISO 8601 (e.g., "2026-01-30T14:30:00Z"). Examples: - Korea carrier: "2026-01-30 14:30" → "2026-01-30T14:30:00+09:00" (KST) - USPS: "January 30, 2026, 2:30 pm EST" → "2026-01-30T14:30:00-05:00" (EST) - DHL: "30.01.2026 14:30" → "2026-01-30T14:30:00Z" timeUnknown: description: >- Whether the time portion of `timestamp` is an estimate rather than a value the carrier provided (optional). Some carriers give only a **date** for certain events and no scan time — USPS does this for events like "In Transit to Next Facility" and "Pre-Shipment". In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and this field is `true`. Absent or `false` means the carrier supplied the time itself. type: boolean status: type: string enum: - pending - in_transit - out_for_delivery - delivered - failed - returned - cancelled - unknown description: >- Delivery status (WhereParcel standardized) The standardized value of the TrackingStatus type. It converts the various status codes of carriers into 8 standard statuses. Examples: - Logen "Picked up" → "in_transit" - FedEx "DEL" → "delivered" - USPS "Out for Delivery" → "out_for_delivery" - Japan carrier "配達完了" → "delivered" location: type: string description: >- Location information (WhereParcel standardized, optional) The physical location where the event occurred. It standardizes the differing location notation methods of each carrier as much as possible. Examples: - South Korea: "Seoul, Gangnam-gu, Teheran-ro", "Busan, Buk-gu logistics center" - USPS: "NEW YORK NY DISTRIBUTION CENTER" - FedEx: "MEMPHIS, TN" - DHL: "Frankfurt Gateway" Note: Some carriers may not provide location information. description: type: string description: >- Event description (WhereParcel standardized) A detailed description of the event. It is converted to English and provided whenever possible. Examples: - South Korea: "Arrived at Namgwanak" - FedEx: "Delivered. Signed by: JOHN DOE" (original: "Delivered. Signed by JOHN DOE") - USPS: "Out for delivery" (original: "Out for Delivery") - DHL: "Customs clearance completed" (original: "Customs clearance completed") rawStatus: type: string description: >- Carrier original status code (optional) Preserves the status code/text actually displayed by the carrier exactly as-is. Provided so that customers can compare it with the carrier's official site. Examples: - Logen: "Picked up", "In transit", "Delivered" - CJ Logistics: "Received", "Out for delivery", "Delivered" - FedEx: "PU" (Picked up), "IT" (In transit), "DEL" (Delivered) - USPS: "Acceptance", "In Transit", "Delivered" - DHL: "Picked up", "Clearance event", "Delivered" Note: This field matches the "Status" column on the carrier's official site. rawDescription: type: string description: >- Carrier original description (optional) Preserves the event description actually displayed by the carrier exactly as-is. Unlike description, it is provided in its original form without language conversion or standardization. Examples: - Logen: "Arrived at Namgwanak" - CJ Logistics: "Loaded onto line-haul" - FedEx: "Delivered. Left at front door. Signature Service not requested." - USPS: "Out for Delivery, Expected Delivery by 8:00pm" - DHL: "Clearance event - Import clearance completed" - China carrier: "【广州市】已到达 广州转运中心" (original Chinese preserved) Note: This field matches the "Details" column on the carrier's official site. required: - timestamp - status - description additionalProperties: false description: >- Delivery event (individual delivery record) Represents the movement record at each stage of the parcel. Sorted chronologically so that the delivery history can be tracked. description: >- List of delivery events The delivery history sorted chronologically. The most recent event is located at the end of the array. Examples: - events[0]: First event (oldest record) - events[events.length - 1]: Last event (most recent record) from: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Origin information (optional) Location information from which the parcel was shipped. For privacy protection, the name may be masked. Examples: - name: "Hong*dong" (individual: masked), "Coupang" (company: original) - address: "Seoul, Gangnam-gu", "Tokyo, Japan" Note: Some carriers may not provide origin information. to: type: object properties: name: type: string address: type: string additionalProperties: false description: >- Destination information (optional) Location information to which the parcel will be delivered. For privacy protection, the name and detailed address may be masked. Examples: - name: "Kim*su" (individual: masked), "ABC Company" (company: original) - address: "Seoul, Seocho-gu" (detailed address excluded) Note: Some carriers may not provide destination information. signedBy: type: string description: >- Signer information (optional) The name of the person who signed upon delivery completion. Mainly provided by North American/European carriers (FedEx, UPS, DHL, etc.). Examples: - "JOHN DOE" - "Front Desk" - "Receptionist" Note: - Most Korean/Asian carriers do not provide this. - Unattended delivery (e.g., doorstep delivery) is null. weight: type: object properties: value: type: number unit: type: string enum: - kg - lb - g required: - value - unit additionalProperties: false description: |- Weight information (optional) The weight of the parcel. Mainly provided for international shipments. Examples: - { value: 2.5, unit: "kg" } - { value: 5.5, unit: "lb" } Note: Most domestic parcels do not provide weight information. deliveryInstructions: type: string description: |- Delivery instructions (optional) Delivery-related instructions requested by the customer. Examples: - "Please leave it with the security office if I am away" - "Leave at front door" - "Call before delivery" - "配達前に電話してください" (Japanese) Note: Most carriers do not provide this. lastUpdated: type: string description: >- Last update date/time (ISO 8601 format) The time when WhereParcel retrieved the data from the carrier. Used to determine the freshness of cached data. Examples: - "2026-01-30T15:30:00Z" Note: This value is not the carrier's last update time. required: - deliveryStatus - events - lastUpdated additionalProperties: false description: >- Tracking data (full delivery information) Contains the full delivery information for a specific tracking number. All fields are converted to and provided in the WhereParcel standard format. error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false description: API error (common) required: - carrier - trackingNumber - status additionalProperties: false description: Tracking entry item (for webhook Payload) timestamp: type: string required: - requestId - trackingItems - timestamp additionalProperties: false description: |- Tracking entry array webhook Payload - first.tracked: First tracking completed (all items) - tracking.completed: Tracking completed (all items, including success/failure) - status.changed: Status changed (changed items only) CarrierInfo: type: object properties: code: type: string description: |- Carrier code A unique identifier defined by WhereParcel. Format: {countryCode}.{carrierName} Examples: - 'kr.post' (South Korea, Korea Post) - 'kr.cj' (CJ Logistics) - 'us.fedex' (FedEx) - 'us.usps' (USPS) - 'intl.dhl' (DHL international shipping) name: anyOf: - type: string - type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support description: |- Carrier name A single-language string or a multilingual object. Examples: - "Korea Post" (string) - { ko: "Korea Post Parcel", en: "Korea Post" } (multilingual) serviceScope: type: string enum: - national - international description: |- Service scope The delivery scope provided by the carrier. - 'national': Domestic delivery only (e.g., South Korea → South Korea) - 'international': International delivery (e.g., South Korea → USA) country: type: string description: |- Country code (ISO 3166-1 alpha-2) The country where the carrier's headquarters is located, or its main country of operation. Examples: - 'KR': South Korea - 'US': USA - 'JP': Japan - 'CN': China - 'DE': Germany - 'INTL': International shipping only (country cannot be specified) region: type: string description: |- Region code (optional) Used when carriers differ by region, as in the USA. Examples: - 'CA': California - 'TX': Texas - 'NY': New York Note: Most countries do not use this field. trackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: |- Tracking number pattern (optional) A description of the valid tracking number format. It can be used for client-side validation. Examples: - { regex: '^[0-9]{10,13}$', description: '10-13 digit number' } - { regex: '^[A-Z]{2}[0-9]{9}[A-Z]{2}$', description: '2 letters + 9 digits + 2 letters' } postalCode: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: |- Postal code field requirement (for public API) Only requirement is exposed. validation/message are managed in CarrierMetadata. phoneNumber: type: object properties: requirement: type: string enum: - optional - required description: >- Additional input field requirement level Some carriers (e.g., GLS Germany) require additional input such as a postal code or mobile phone number in addition to the tracking number. This type defines the requirement level of each field. - 'required': Required (tracking is rejected if missing; blocked before billing at the validation stage) - 'optional': Optional (basic tracking is possible without it; provides detailed information if present) required: - requirement additionalProperties: false description: Phone number field requirement (for public API) required: - code - name - serviceScope - country additionalProperties: false description: >- Carrier information (for public API) Carrier metadata provided to customers. It does not include internal implementation information (providerType, developmentStatus). LocalizedName: type: object properties: en: type: string ko: type: string ja: type: string de: type: string it: type: string es: type: string required: - en - ko additionalProperties: false description: Multilingual name support TrackingNumberPattern: type: object properties: regex: type: string description: type: string examples: type: array items: type: string required: - regex - description additionalProperties: false description: Tracking number pattern definition tags: - name: Tracking description: Parcel tracking API - name: Carriers description: Carrier metadata - name: Webhooks description: Webhook subscription management - name: Webhook Endpoints description: Webhook endpoint configuration paths: /v2/track: post: operationId: trackParcels summary: Track parcels (billable) description: > Track up to 5 parcels at once. Average response time 5 seconds per item. Supports 64+ carriers including USPS, UPS, FedEx, DHL, and more. **Some carriers are limited to 1 item per request:** The carriers listed below take substantially longer to look up, so a single synchronous request may contain **at most 1 item across all of them combined** — mixing two of them in one request is rejected as well. You can still batch them with other carriers: 1 item from this list + up to 4 items from any other carrier = 5 items total. `us.ups`, `us.usps`, `us.fedex`, `us.dhl`, `us.dhl.express`, `us.dhl.ecommerce`, `intl.ups`, `intl.usps`, `intl.fedex`, `intl.dhl`, `gb.royalmail`, `gb.royalmail.special`, `gb.evri`, `gb.ups`, `ca.ups`, `ca.fedex`, `de.ups`, `es.ups`, `ie.ups`, `au.post` This list may change. Exceeding the limit returns `INVALID_REQUEST`, and the error message names the exact carriers that triggered it. To track several items from these carriers, use `/v2/webhooks/register` (up to 100 items, asynchronous). **Events without a time:** some carriers give only a date for certain events and no scan time (USPS does this for "In Transit to Next Facility" and "Pre-Shipment"). In that case `timestamp` is filled with noon on that date to stay valid ISO 8601, and the event carries `timeUnknown: true`. When the field is absent, the time came from the carrier and is real. **When to use this endpoint:** Use `/v2/track` for on-demand, one-off lookups — for example, when a customer checks their order status on your website. **For continuous monitoring, use Webhooks instead.** If you need to keep your database in sync with delivery status (e.g., updating order records, triggering notifications), register a webhook subscription via `/v2/webhooks/register` with `recurring: true`. The webhook approach is far more efficient — instead of polling repeatedly, you receive a push notification only when the status actually changes. **Rate Limits:** Each API key has per-minute and per-month request quotas based on your plan. When exceeded, the API returns HTTP 429. See response headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` for current usage. | Plan | Requests/min | Requests/month | |------|-------------|----------------| | Starter | 30 | 10,000 | | Pro | 60 | 30,000 | | Business | 200 | 300,000 | tags: - Tracking security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkTrackingRequest' example: trackingItems: - carrier: us.ups trackingNumber: 1Z999AA10123456784 - carrier: us.ontrac trackingNumber: D10017048734180 responses: '200': description: Successful tracking response content: application/json: schema: $ref: '#/components/schemas/BulkTrackingResponse' example: success: true results: - carrier: us.fedex trackingNumber: '231300687629630' clientId: order-123 status: success billable: true cached: false data: deliveryStatus: delivered events: - timestamp: '2026-02-05T14:30:00-05:00' status: delivered location: New York, NY description: Delivered, left at front door - timestamp: '2026-02-05T09:15:00-05:00' status: out_for_delivery location: Brooklyn, NY description: On FedEx vehicle for delivery - timestamp: '2026-02-04T18:00:00-05:00' status: in_transit location: Newark, NJ description: At local FedEx facility from: name: J. Smith to: name: M. Johnson lastUpdated: '2026-02-05T14:30:00-05:00' - carrier: us.usps trackingNumber: '9400111899223197428490' status: success billable: true cached: false data: deliveryStatus: in_transit events: - timestamp: '2026-02-05T12:00:00-05:00' status: in_transit location: Chicago, IL description: In transit to next facility lastUpdated: '2026-02-05T12:00:00-05:00' '401': description: Authentication failed - API key missing or invalid content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. /v2/carriers: get: operationId: listCarriers summary: List supported carriers description: Retrieve list and metadata of 64+ carriers. Free API - does not count towards usage quota. tags: - Carriers security: - ApiKeyAuth: [] responses: '200': description: Carrier list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListCarriersResponse' example: success: true data: - us.fedex - us.ups - us.usps - us.usps - us.fedex '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key /v2/countries: get: operationId: listCountries summary: List supported countries description: Retrieve list of countries supported for parcel tracking. Free API - does not count towards usage quota. tags: - Carriers security: - ApiKeyAuth: [] responses: '200': description: Country list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListCountriesResponse' example: success: true data: - kr - us - jp - cn - de '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key /v2/carriers/{countryCode}: get: operationId: getCarriersByCountry summary: Get carriers by country description: Filter and retrieve carriers available in a specific country. Free API - does not count towards usage quota. tags: - Carriers security: - ApiKeyAuth: [] parameters: - name: countryCode in: path required: true description: Country code (ISO 3166-1 alpha-2) schema: type: string example: us responses: '200': description: Country-specific carriers retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetCarriersByCountryResponse' example: success: true data: - us.fedex - us.ups - us.usps - us.usps '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key '404': description: Country code not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: NOT_FOUND message: Country code not found /v2/carriers/{countryCode}/{region}: get: operationId: getCarriersByRegion summary: Get carriers by country and region description: > Filter and retrieve carriers available in a specific region of a country. Useful for countries with large territories (e.g., USA, China) where some carriers operate only in specific regions. Not needed for countries like Korea where all carriers operate nationwide. Free API - does not count towards usage quota. tags: - Carriers security: - ApiKeyAuth: [] parameters: - name: countryCode in: path required: true description: Country code (ISO 3166-1 alpha-2) schema: type: string example: us - name: region in: path required: true description: Region code (state, province, etc.) schema: type: string example: ca responses: '200': description: Region-specific carriers retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetCarriersByRegionResponse' example: success: true data: - us.usps - us.fedex - us.ups '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key '404': description: Country or region code not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: NOT_FOUND message: Country or region code not found /v2/webhooks/register: post: operationId: registerWebhook summary: Register webhook (billable) description: > Register a webhook for parcel tracking. Supports 2 modes: - `recurring: true` — Continuous monitoring until delivery (subscription). **Recommended for most integrations.** Register once and receive push notifications whenever the tracking status changes. Ideal for keeping your database in sync with delivery progress. - `recurring: false` — Query once only (one-time, default). Useful for one-off lookups where you don't need ongoing updates. **Why use webhooks?** Polling `/v2/track` repeatedly wastes your request quota. A single parcel typically has 5–10 status changes over its lifecycle. With webhooks, you receive only those 5–10 updates instead of making hundreds of polling requests. Billable API, supports up to 100 items per registration. **What we POST to your endpoint.** Content-Type is `application/json`; we expect a 2xx response within 10 seconds. Redirects are not followed. ```json { "event": "tracking.updated", "timestamp": "2026-08-21T04:15:22.184Z", "data": { "requestId": "req_abc123", "timestamp": "2026-08-21T04:15:22.100Z", "trackingItems": [ { "carrier": { "code": "us.usps", "name": "USPS", "country": "US" }, "trackingNumber": "9400111206206406260787", "status": "success", "currentStatus": "in_transit", "hasChange": true, "trackingData": { "deliveryStatus": "in_transit", "events": [] } } ], "isPeriodicUpdate": true, "hasChanges": true, "changedItemCount": 1, "queriedItemCount": 1, "deliveredItemCount": 0, "changeId": "chg_xyz789" } } ``` **Fields:** `event` — `tracking.registered` on the first lookup after you register, `tracking.updated` on every later poll. `data.requestId` — the subscription id returned by this endpoint. `data.trackingItems[]` — one entry per tracked parcel. `carrier` is an object (`code`, `name`, `country`), not a string. `status` is `success` or `error`. `currentStatus` is the standardized delivery status. `trackingData` holds the full result. `hasChange` marks items whose status changed in this cycle. `data.isPeriodicUpdate`, `hasChanges`, `changedItemCount`, `queriedItemCount`, `deliveredItemCount`, `changeId` — present only on recurring updates, not on the first `tracking.registered` delivery. **Headers:** `X-WhereParcel-Event`, `X-WhereParcel-Timestamp`, and `X-WhereParcel-Signature` — an HMAC-SHA256 hex digest of the exact raw JSON body, keyed with your endpoint secret. Verify it by recomputing the digest over the raw body before parsing. **If you register without `webhookEndpointId`, nothing is pushed to you.** That is the pull mode: retrieve results with `GET /v2/webhooks/subscriptions/{requestId}` or `POST /v2/webhooks/results`. To receive the payload above, create an endpoint with `POST /v2/webhook-endpoints` and pass its id as `webhookEndpointId`. tags: - Webhooks security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterWebhookRequest' examples: recurring: summary: Recurring (continuous monitoring) value: trackingItems: - carrier: us.fedex trackingNumber: '123456789012' clientId: order-001 - carrier: us.fedex trackingNumber: '612938472651' postalCode: '10001' clientId: order-002 recurring: true webhookEndpointId: endpoint-id-123 oneTime: summary: One-time (single lookup) value: trackingItems: - carrier: us.ups trackingNumber: 1Z999AA10123456784 recurring: false responses: '200': description: Webhook registered successfully content: application/json: schema: oneOf: - $ref: '#/components/schemas/RegisterWebhookRecurringResponse' - $ref: '#/components/schemas/RegisterWebhookOneTimeResponse' examples: recurring: summary: Recurring response value: mode: recurring requestId: req_abc123xyz trackingItemCount: 2 webhookEndpointId: endpoint-id-123 createdAt: '2026-02-05T10:00:00.000Z' oneTime: summary: One-time response value: mode: one-time requestId: req_ghi789rst webhookDelivered: false progress: total: 1 completed: 1 succeeded: 1 failed: 0 percentage: 100 results: - carrier: us.ups trackingNumber: 1Z999AA10123456784 status: success data: deliveryStatus: in_transit events: - timestamp: '2026-02-05T12:00:00-05:00' status: in_transit location: Chicago, IL description: Departed facility lastUpdated: '2026-02-05T12:00:00-05:00' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. /v2/webhooks/subscriptions: get: operationId: listWebhookSubscriptions summary: List webhook subscriptions description: >- Retrieve all registered webhook subscriptions (recurring + one-time). Free API - does not count towards usage quota. tags: - Webhooks security: - ApiKeyAuth: [] responses: '200': description: Subscription list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListTrackingRequestsResponse' example: - requestId: req_abc123xyz trackingItemCount: 2 trackingItems: - carrier: us.fedex trackingNumber: '300718039335' clientId: order-001 latestStatus: delivered - carrier: us.usps trackingNumber: '9400111899223197428491' latestStatus: in_transit recurring: true webhookEndpointId: endpoint_xyz789 isActive: true createdAt: '2026-02-05T10:00:00.000Z' updatedAt: '2026-02-05T14:30:00.000Z' - requestId: req_def456uvw trackingItemCount: 1 trackingItems: - carrier: us.usps trackingNumber: '9400111899223197428492' latestStatus: out_for_delivery recurring: false isActive: false progress: total: 1 completed: 1 succeeded: 1 failed: 0 percentage: 100 createdAt: '2026-02-04T09:00:00.000Z' updatedAt: '2026-02-04T09:05:00.000Z' completedAt: '2026-02-04T09:05:00.000Z' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' /v2/webhooks/subscriptions/{requestId}: get: operationId: getWebhookSubscription summary: Get webhook subscription description: >- Retrieve webhook subscription information for a specific requestId. Free API - does not count towards usage quota. tags: - Webhooks security: - ApiKeyAuth: [] parameters: - name: requestId in: path required: true description: requestId received during webhook registration schema: type: string example: req_abc123xyz responses: '200': description: Subscription info retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetWebhookSubscriptionResponse' example: success: true data: requestId: req_abc123xyz userId: user_abc123 apiKeyId: key_def456 trackingItems: - carrier: us.fedex trackingNumber: '123456789012' clientId: order-001 latestStatus: in_transit usageCounted: true status: success trackingData: deliveryStatus: in_transit events: - timestamp: '2026-02-05T09:15:00-05:00' status: in_transit location: Newark, NJ description: At local FedEx facility lastUpdated: '2026-02-05T10:00:00-05:00' trackingIndex: - us.fedex:123456789012 clientIdIndex: - order-001 recurring: true webhookEndpointId: endpoint-id-123 isActive: true createdAt: '2026-02-05T10:00:00.000Z' updatedAt: '2026-02-05T10:00:00.000Z' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: requestId not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' delete: operationId: deleteWebhookSubscription summary: Delete webhook subscription description: >- Cancel a webhook subscription and stop monitoring. For recurring webhooks, monitoring stops immediately. Free API - does not count towards usage quota. tags: - Webhooks security: - ApiKeyAuth: [] parameters: - name: requestId in: path required: true description: requestId of the webhook to delete schema: type: string example: req_abc123xyz responses: '200': description: Subscription deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteTrackingRequestResponse' example: deleted: true requestId: req_abc123xyz message: Webhook subscription deleted successfully '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: requestId not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' /v2/webhooks/subscriptions/{requestId}/changes: get: operationId: listWebhookChanges summary: List webhook change history description: >- Retrieve all change history (delivery status changes) for a specific webhook subscription. Free API - does not count towards usage quota. tags: - Webhooks security: - ApiKeyAuth: [] parameters: - name: requestId in: path required: true description: requestId received during webhook registration schema: type: string example: req_abc123xyz - name: limit in: query required: false description: Maximum number of records to return (default 20, max 100). Newest first. schema: type: integer default: 20 maximum: 100 responses: '200': description: Change history retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListTrackingChangesResponse' example: success: true data: requestId: req_abc123xyz changes: - changeId: change_1770282900000 timestamp: '2026-02-05T09:15:00.000Z' changedItemCount: 1 preview: trackingNumbers: - 1Z999AA10123456784 - changeId: change_1770301800000 timestamp: '2026-02-05T14:30:00.000Z' changedItemCount: 2 preview: trackingNumbers: - 1Z999AA10123456784 - 1Z999AA10123456785 pagination: limit: 20 hasMore: false '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: requestId not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' /v2/webhooks/subscriptions/{requestId}/changes/{changeId}: get: operationId: getWebhookChange summary: Get single change event description: Retrieve detailed information for a specific change event. Free API - does not count towards usage quota. tags: - Webhooks security: - ApiKeyAuth: [] parameters: - name: requestId in: path required: true description: requestId received during webhook registration schema: type: string example: req_abc123xyz - name: changeId in: path required: true description: Change event ID schema: type: string example: change_def456 responses: '200': description: Change event retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetTrackingChangeResponse' example: success: true data: changeId: change_1770282900000 requestId: req_abc123xyz timestamp: '2026-02-05T09:15:00.000Z' changedItemCount: 1 changedItems: - carrier: us.ups trackingNumber: 1Z999AA10123456784 previousStatus: in_transit currentStatus: out_for_delivery trackingData: deliveryStatus: out_for_delivery lastUpdated: '2026-02-05T09:15:00.000Z' events: - timestamp: '2026-02-05T08:00:00+09:00' status: in_transit location: Newark, NJ description: In transit - timestamp: '2026-02-05T09:15:00+09:00' status: out_for_delivery location: New York, NY description: Out for delivery '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: requestId or changeId not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' /v2/webhooks/results: post: operationId: searchWebhookResultsBatch summary: Batch search webhook results description: | Search webhook results for multiple parcels at once. Use this to retrieve final results of registered webhooks. **Search methods:** - Search by carrier + trackingNumber - Search by clientId - Both methods can be used simultaneously **How it works:** - Searches using trackingIndex/clientIdIndex fields in the tracking_requests collection - Returns only the latest document when multiple documents exist for the same tracking number - Batch processed due to Firestore array-contains-any limit (10) (up to 10 queries for 100 items) Free API - does not count towards usage quota. tags: - Webhooks security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchWebhookResultsBatchRequest' examples: byTracking: summary: Search by tracking number value: trackingItems: - carrier: us.fedex trackingNumber: '300718039335' - carrier: us.fedex trackingNumber: '612938472651' postalCode: '10001' byClientId: summary: Search by clientId value: trackingItems: - clientId: order-001 - clientId: order-002 mixed: summary: Mixed search (tracking number + clientId) value: trackingItems: - carrier: us.fedex trackingNumber: '300718039335' - clientId: order-002 responses: '200': description: Batch search completed successfully content: application/json: schema: $ref: '#/components/schemas/SearchWebhookResultsBatchResponse' example: results: us.fedex:300718039335: source: bulk data: deliveryStatus: delivered events: - timestamp: '2026-02-05T14:30:00-05:00' status: delivered location: New York, NY description: Delivered, left at front door - timestamp: '2026-02-05T09:15:00-05:00' status: out_for_delivery location: New York, NY description: Out for delivery lastUpdated: '2026-02-05T14:30:00-05:00' status: delivered jobId: job_abc123xyz createdAt: '2026-02-05T10:00:00.000Z' clientId:order-002: source: bulk data: deliveryStatus: in_transit events: - timestamp: '2026-02-05T12:00:00-05:00' status: in_transit location: Chicago, IL description: In transit to next facility lastUpdated: '2026-02-05T12:00:00-05:00' status: in_transit jobId: job_def456uvw createdAt: '2026-02-05T10:00:00.000Z' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid API key /v2/webhook-endpoints: post: operationId: createWebhookEndpoint summary: Create webhook endpoint description: | Pre-register a URL to receive webhooks. Registered endpoints can be referenced by webhookEndpointId during webhook registration. Free API - does not count towards usage quota. tags: - Webhook Endpoints security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookEndpointRequest' example: name: Production Webhook url: https://myapp.com/webhooks/whereparcel description: Production webhook receiver URL responses: '201': description: Endpoint created successfully content: application/json: schema: $ref: '#/components/schemas/CreateWebhookEndpointResponse' example: success: true data: endpointId: endpoint_abc123 name: Production Webhook url: https://myapp.com/webhooks/whereparcel secret: whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456 description: Production webhook receiver URL isActive: true createdAt: '2026-02-05T10:00:00.000Z' '400': description: Bad request (invalid URL format, etc.) content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' get: operationId: listWebhookEndpoints summary: List webhook endpoints description: Retrieve all registered webhook endpoints. Free API - does not count towards usage quota. tags: - Webhook Endpoints security: - ApiKeyAuth: [] responses: '200': description: Endpoint list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListWebhookEndpointsResponse' example: success: true data: - endpointId: endpoint_abc123 name: Production Webhook url: https://myapp.com/webhooks/whereparcel description: Production webhook receiver URL isActive: true createdAt: '2026-02-05T10:00:00.000Z' updatedAt: '2026-02-05T10:00:00.000Z' - endpointId: endpoint_def456 name: Staging Webhook url: https://staging.myapp.com/webhooks/whereparcel description: Staging webhook receiver URL isActive: false createdAt: '2026-02-04T15:30:00.000Z' updatedAt: '2026-02-04T16:00:00.000Z' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' /v2/webhook-endpoints/{endpointId}: put: operationId: updateWebhookEndpoint summary: Update webhook endpoint description: | Update webhook endpoint information. You can change the URL, name, description, active status, etc. Free API - does not count towards usage quota. tags: - Webhook Endpoints security: - ApiKeyAuth: [] parameters: - name: endpointId in: path required: true description: Endpoint ID to update schema: type: string example: endpoint_abc123 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWebhookEndpointRequest' example: name: Updated Webhook Name url: https://myapp.com/webhooks/new-url enabled: true responses: '200': description: Endpoint updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateWebhookEndpointResponse' example: success: true data: endpointId: endpoint_abc123 name: Updated Webhook Name url: https://myapp.com/webhooks/new-url description: Updated description isActive: true updatedAt: '2026-02-05T11:00:00.000Z' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: endpointId not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' delete: operationId: deleteWebhookEndpoint summary: Delete webhook endpoint description: | Delete a webhook endpoint. Cannot delete an endpoint that is in use by active webhooks. Free API - does not count towards usage quota. tags: - Webhook Endpoints security: - ApiKeyAuth: [] parameters: - name: endpointId in: path required: true description: Endpoint ID to delete schema: type: string example: endpoint_abc123 responses: '200': description: Endpoint deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteWebhookEndpointResponse' example: success: true message: Webhook endpoint deleted successfully '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: endpointId not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '409': description: Cannot delete endpoint that is in use content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse'