swagger: '2.0'
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Track API
  version: '1.123'
  description: 'A simple but powerful logistics API that drives international ecommerce by utilizing a single integration with access to dozens of carriers and global markets. BoxC can complete every leg or only select steps of a shipment''s journey on your behalf with our routing engine.

    '
schemes:
- https
tags:
- name: Track
  x-displayName: Track
  description: "The Track resource allows clients to retrieve tracking events for shipments by their tracking number. You may only track one shipment per request. This endpoint is rate limited.\n\nSome shipments may have <code>images</code> attached to them during transit such as processing scans and proof of delivery. To reveal these images in the response the client must either:\n\n  A. Be the owner of the shipment;<br>\n  B. Provide the shipping email address in the query;<br>\n  C. Provide the postal code in the query if it's not revealed in the event history.\n"
paths:
  /track:
    post:
      tags:
      - Track
      summary: POST /track
      description: Certified Accounts may inject up to 100 events into BoxC's tracking history. Shipments must belong to the user; otherwise, the request will be aborted without events being added.
      operationId: addTrackingEvents
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - write_shipments
      x-badges:
      - name: Beta
        position: after
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  --location 'http://localhost:10000/v1/track' \\\n  -H \"Accept: application/json\" \\\n  -H \"Content-Type: application/json\" \\\n  --data '{\n    \"events\": [\n      {\n        \"tracking_number\": \"CH957707285DE\",\n        \"code\": 105,\n        \"province\": null,\n        \"postal_code\": null,\n        \"city\": \"Shenzhen\",\n        \"country\": \"CN\",\n        \"time\": \"2026-03-11T10:05:08+01:00\"\n      }\n    ]\n  }'\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/definitions/TrackPost'
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/definitions/BadRequest'
              examples:
                notFound:
                  summary: Bad Request
                  description: Shipment not found or doesn't belong to user
                  value:
                    code: 1211
                    message: 'Shipment not found or doesn''t belong to user: %s'
                    errors:
                    - 'Shipment not found or doesn''t belong to user: %s'
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
  /track/{trackingNumber}:
    get:
      tags:
      - Track
      summary: GET /track/{trackingNumber}
      description: Get events for a shipment using its tracking number.
      operationId: getTrackingEvents
      produces:
      - application/json
      security:
      - JWT: []
      parameters:
      - name: trackingNumber
        in: path
        description: The final tracking number or tracking number for a generic shipment label.
        required: true
        type: string
        maxLength: 40
      - name: email
        in: query
        description: The email address of the shipping address. Provide this to reveal images if you're not the owner of the shipment.
        required: false
        type: string
      - name: postal_code
        in: query
        description: The postal code of the shipping address. Provide this to reveal images if you're not the owner of the shipment. It will only work if the postal code is not revealed in the event history.
        required: false
        type: string
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Accept: application/json\" \\\n  https://api.boxc.com/v1/track/{trackingNumber}\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/definitions/Track'
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/definitions/NotFound'
              examples:
                notFound:
                  summary: Not Found
                  description: Shipment not found
                  value:
                    code: 1210
                    message: Shipment not found
                    errors:
                    - Shipment not found
        '429':
          $ref: '#/definitions/RateLimit'
definitions:
  bad-request:
    type: object
    summary: Bad Request
    description: Validation error with the request
    properties:
      code:
        description: Error code. Refer to the list of [Errors](/#tag/Errors).
        type: integer
      message:
        description: Error message explaining the code.
        type: string
      status:
        type: string
        enum:
        - error
        example: error
      errors:
        description: Lists validation errors with the schema or the resource being operated on.
        type: array
        minItems: 1
        maxItems: 5
        items:
          type: string
  NotFound:
    $ref: '#/definitions/not-found'
  Event:
    $ref: '#/definitions/event'
  destination:
    type: object
    properties:
      city:
        type: string
        description: Destination city.
        example: BROOKLYN
      province:
        type: string
        description: Destination province.
        example: NY
      country:
        type: string
        description: Destination country.
        example: US
      port:
        type: string
        description: Destination port.
        example: JFK
    additionalProperties: false
  RateLimit:
    $ref: '#/definitions/rate-limit'
  event:
    type: object
    description: The tracking history for this label in descending order. Set by the system.
    properties:
      carrier:
        description: The carrier that provided this event.
        type: string
        example: USPS
        readOnly: true
      city:
        description: The city the event took place in.
        type: string
        maxLength: 40
        example: New York City
        readOnly: true
      code:
        description: A code matching the description and to help identify the event.
        type: integer
        example: 200
        readOnly: true
      country:
        description: The country code the event took place in.
        type: string
        maxLength: 2
        minLength: 2
        pattern:
        - A-Z
        example: US
        readOnly: true
      description:
        description: A description of the event.
        type: string
        example: DELIVERED
        readOnly: true
      latitude:
        description: Latitude coordinate of the event.
        type:
        - number
        - 'null'
        minimum: -90
        maximum: 90
        example: null
        readOnly: true
      longitude:
        description: Longitude coordinate of the event.
        type:
        - number
        - 'null'
        minimum: -180
        maximum: 180
        example: null
        readOnly: true
      postal_code:
        description: The postal code the event took place in.
        type: string
        maxLength: 10
        example: '10001'
        readOnly: true
      province:
        description: The province the event took place in.
        type: string
        maxLength: 40
        example: NY
        readOnly: true
      time:
        description: The local date and time the event occurred.
        type: string
        format: datetime
        default: null
        example: '2024-05-26 07:11:45'
        readOnly: true
  track-add:
    type: object
    properties:
      events:
        type: array
        description: An array of tracking events to inject.
        minItems: 1
        maxItems: 100
        items:
          type: object
          properties:
            carrier:
              description: The carrier that provided this event.
              type: string
              example: USPS
              readOnly: true
            city:
              description: The city the event took place in.
              type: string
              maxLength: 40
              example: New York
            code:
              description: The BoxC event code. Refer to [Tracking Events](/#tag/TrackingEvents) for descriptions.
              type: integer
              example: 150
              enum:
              - 100
              - 101
              - 102
              - 103
              - 104
              - 105
              - 106
              - 109
              - 110
              - 111
              - 112
              - 113
              - 114
              - 120
              - 121
              - 130
              - 131
              - 132
              - 133
              - 134
              - 135
              - 136
              - 140
              - 150
              - 155
            country:
              description: The country code the event took place in.
              type: string
              maxLength: 2
              minLength: 2
              pattern:
              - A-Z
              example: US
            description:
              description: A description of the event.
              type: string
              example: EN ROUTE
              readOnly: true
            latitude:
              description: Latitude coordinate of the event.
              type:
              - number
              - 'null'
              minimum: -90
              maximum: 90
              default: null
              example: null
            longitude:
              description: Longitude coordinate of the event.
              type:
              - number
              - 'null'
              minimum: -180
              maximum: 180
              default: null
              example: null
            postal_code:
              description: The postal code the event took place in.
              type: string
              maxLength: 10
              example: '10001'
              default: null
            province:
              description: The province the event took place in.
              type: string
              maxLength: 40
              example: NY
              default: null
            time:
              description: The local date and time the event occurred.
              type: string
              format: datetime
              example: '2024-05-26 07:11:45'
            tracking_number:
              description: The tracking number for the event.
              type: string
              maxLength: 40
              example: CH957707285DE
          required:
          - time
          - code
          - city
          - country
          - tracking_number
    required:
    - events
  BadRequest:
    $ref: '#/definitions/bad-request'
  rate-limit:
    description: Too Many Requests
    content:
      application/json:
        schema:
          type: object
          summary: Too Many Requests
          description: Error for too many requests in a given time frame. See [Rate Limits](/#tag/RateLimit) for more information.
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          rateLimit:
            summary: Too Many Requests
            description: Too many requests. Please wait before trying again.
            value:
              code: 1015
              message: Too many requests. Please wait before trying again.
              errors:
              - Too many requests. Please wait before trying again.
  ShipmentImages:
    $ref: '#/definitions/shipment-images'
  shipment-images:
    description: Lists URLs of images taken during transit and categorized by type of photo. URLs expire after a period of time so refer to the `expires` query parameter.
    type: object
    readOnly: true
    properties:
      pod:
        type: array
        default: []
        readOnly: true
        example:
        - https://storage.googleapis.com/boxc_shipments_us/images/pod/i67e4226fb291a5.123123123.jpeg?fingerprint=06d7de3c7c8c0f5c&expires=1758556271
        items:
          type: string
      scans:
        type: array
        default: []
        readOnly: true
        example:
        - https://storage.googleapis.com/boxc_shipments_us/images/scans/i67e4226fb291a6.1231232131.jpeg?fingerprint=15d7de3c7c8c0f5c&expires=1758556271
        items:
          type: string
  track:
    type: object
    properties:
      track:
        type: object
        properties:
          carrier:
            description: The last mile carrier code for the shipment.
            type: string
            format: string
            default: null
            example: DHLeC
          created:
            description: The date and time the shipment was created.
            type: string
            example: '2024-06-30T17:14:10+00:00'
            readOnly: true
          destination:
            type: object
            $ref: '#/definitions/Destination'
          entry_point:
            description: The shipment origin code.
            type: string
            example: HKG101
          events:
            description: A list of tracking events sorted in descending order chronologically.
            type: array
            items:
              $ref: '#/definitions/Event'
          has_images:
            description: Indicates this shipment has images.
            type: boolean
            readOnly: true
            example: true
          images:
            $ref: '#/definitions/ShipmentImages'
          order_number:
            description: The shipment order number.
            type: string
            maxLength: 40
            default: null
            example: ABC1234-583
          service:
            description: The shipment service name.
            type: string
            example: BoxC Parcel
          shipment_id:
            description: The shipment ID.
            type: integer
            example: 10002312
          status:
            description: The tracking status of the shipment.
            type: string
            example: En Route
          tracking_number:
            type: string
            description: The shipment tracking number.
            example: '9261290198179000000172'
        additionalProperties: false
  Unauthorized:
    $ref: '#/definitions/unauthorized'
  Forbidden:
    $ref: '#/definitions/forbidden'
  forbidden:
    description: Forbidden
    content:
      application/json:
        schema:
          type: object
          summary: Forbidden
          description: Error relating to insufficient permissions for a resource
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          revoked:
            summary: Forbidden Authorization Revoked
            description: 'Forbidden: Authorization revoked'
            value:
              code: 1008
              message: 'Forbidden: Authorization revoked'
              errors:
              - 'Forbidden: Authorization revoked'
          scope:
            summary: Forbidden Scope
            description: 'Forbidden: Missing required scope'
            value:
              code: 1009
              message: 'Forbidden: Missing required scope'
              errors:
              - 'Forbidden: Missing required scope'
  Destination:
    $ref: '#/definitions/destination'
  Track:
    $ref: '#/definitions/track'
  unauthorized:
    description: Unauthorized
    content:
      application/json:
        schema:
          type: object
          summary: Unauthorized
          description: Lack of valid authentication credentials for the resource
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          accessToken:
            summary: Invalid access token
            description: Invalid access token
            value:
              code: 1005
              message: Invalid access token
              errors:
              - Invalid access token
  not-found:
    type: object
    summary: Not Found
    description: Object not found or not owned by the user
    properties:
      code:
        description: Error code. Refer to the list of [Errors](/#tag/Errors).
        type: integer
      message:
        description: Error message explaining the code.
        type: string
      status:
        type: string
        enum:
        - error
        example: error
      errors:
        description: Duplicate of the error message
        type: array
        items:
          type: string
  TrackPost:
    $ref: '#/definitions/track-add'
securityDefinitions:
  JWT:
    type: http
    scheme: bearer
    bearerScheme: JWT
    in: header
    description: All operations require a JSON Web Token after completing an [OAuth2 flow](#tag/Authentication).
  PrivilegedClient:
    type: http
    scheme: bearer
    bearerScheme: JWT
    description: Some clients require special privileges to use operations. No additional scope is needed.
x-servers:
- url: https://api.boxc.com/v1
x-tagGroups:
- name: Overview
  tags:
  - Introduction
  - Authentication
  - RateLimit
  - Paginate
  - Changelog
- name: Operations
  tags:
  - CalculateDuty
  - Classify
  - Invoices
  - Users
  - ValidateAddress
  - Webhooks
- name: Shipping
  tags:
  - Credentials
  - CustomsProducts
  - EntryPoints
  - Estimate
  - Labels
  - Manifests
  - Overpacks
  - Shipments
  - Track
- name: Fulfillment
  tags:
  - Inbound
  - Orders
  - Products
  - Shops
  - Warehouses
- name: Returns
  tags:
  - Reshipments
  - Returns
- name: Data
  tags:
  - CarrierCredentials
  - DangerousGoods
  - Errors
  - Languages
  - CarrierParameters
  - ReturnsProcess
  - TrackingEvents