Boxc Track API

openapi: 3.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.

    '
servers:
- url: https://api.boxc.com/v1
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
      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: '#/components/schemas/TrackPost'
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/schemas/Unauthorized'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '429':
          $ref: '#/components/schemas/RateLimit'
  /track/{trackingNumber}:
    get:
      tags:
      - Track
      summary: GET /track/{trackingNumber}
      description: Get events for a shipment using its tracking number.
      operationId: getTrackingEvents
      security:
      - JWT: []
      parameters:
      - name: trackingNumber
        in: path
        description: The final tracking number or tracking number for a generic shipment label.
        required: true
        schema:
          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
        schema:
          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
        schema:
          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: '#/components/schemas/Track'
        '401':
          $ref: '#/components/schemas/Unauthorized'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                notFound:
                  summary: Not Found
                  description: Shipment not found
                  value:
                    code: 1210
                    message: Shipment not found
                    errors:
                    - Shipment not found
        '429':
          $ref: '#/components/schemas/RateLimit'
components:
  schemas:
    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
    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.
    RateLimit:
      $ref: '#/components/schemas/rate-limit'
    Forbidden:
      $ref: '#/components/schemas/forbidden'
    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: '#/components/schemas/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: '#/components/schemas/Event'
            has_images:
              description: Indicates this shipment has images.
              type: boolean
              readOnly: true
              example: true
            images:
              $ref: '#/components/schemas/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
    Destination:
      $ref: '#/components/schemas/destination'
    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
    Event:
      $ref: '#/components/schemas/event'
    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
    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'
    NotFound:
      $ref: '#/components/schemas/not-found'
    ShipmentImages:
      $ref: '#/components/schemas/shipment-images'
    TrackPost:
      $ref: '#/components/schemas/track-add'
    Unauthorized:
      $ref: '#/components/schemas/unauthorized'
    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
    Track:
      $ref: '#/components/schemas/track'
    BadRequest:
      $ref: '#/components/schemas/bad-request'
    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
    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
    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
  securitySchemes:
    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