Boxc Overpacks API

openapi: 3.2.0
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Overpacks 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: Overpacks
  x-displayName: Overpacks
  description: 'The Overpacks resource allows a user to combine many Shipments into one object for faster clearance with BoxC and Customs. An overpack can be a carton, container, pallet, or bag. Regardless, it must contain an overpack label on the outside. Empty overpacks are routinely purged from the system.


    When creating an overpack it''s recommended to provide one or more shipment ID, label ID, or tracking numbers in the request. The overpack will inherit the first shipment''s (`n`) attributes like the `entry_point`, `service`, `terms`, etc. All shipments require identical attributes to be a part of the same overpack. Errors will be returned if the `n + 1` shipments do not match the first one. An error message will be present in the `shipments` array for each shipment that fails while creating or updating overpacks. Shipments that pass validation will still be added in the same request.


    The system will calculate the routing and other applicable carrier logic to determine the physical appearance of the label. Some carriers require custom messaging on the labels while others require a completely different label altogether. The system handles this logic on your behalf.


    **Note:** Shipments without labels and cancelled shipments can''t be added to overpacks.


    The overpack(s) must be dropped off at the BoxC collection center indicated by the `entry_point`. Some entry points do not require overpacking and the system will prevent you from creating one. Deleting an overpack unassigns all shipments from it.


    **Note:** A client won''t be able to print an overpack label until at least one shipment is assigned to it.'
paths:
  /overpacks:
    get:
      tags:
      - Overpacks
      summary: GET /overpacks
      description: Retrieves a paginated list of overpacks.
      operationId: getOverpacks
      security:
      - JWT:
        - read_shipments
      parameters:
      - in: query
        name: limit
        description: The number of results to return.
        required: false
        schema:
          type: string
          default: 50
          maximum: 100
          minimum: 50
      - in: query
        name: order
        description: The sort order of the results.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - in: query
        name: page_token
        description: Used for selecting the page after the initial query.
        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/overpacks\\?limit=100\\&order=desc\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  overpacks:
                    type: array
                    items:
                      $ref: '#/components/schemas/OverpackList'
                  next_page:
                    type: string
                    description: Page token. Set by the system.
                    example: ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZsYXN0X2lkPTE1Mzg0Nw
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                invalidToken:
                  summary: Bad Request
                  description: Invalid page token
                  value:
                    code: 1025
                    message: Invalid page token
                    errors:
                    - Invalid page token
        '401':
          $ref: '#/components/schemas/Unauthorized'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '429':
          $ref: '#/components/schemas/RateLimit'
    post:
      tags:
      - Overpacks
      summary: POST /overpacks
      description: Creates an overpack.
      operationId: addOverpack
      security:
      - JWT:
        - write_shipments
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/overpacks \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"overpack\": {\n      \"height\": 50,\n      \"length\": 91,\n      \"shipments\": [\n        {\n          \"id\": <YOUR SHIPMENT ID>,\n          \"label_id\": <YOUR LABEL ID>,\n          \"tracking_number\": \"<YOUR TRACKING NUMBER>\"\n        }\n      ],\n      \"weight\": 87.5,\n      \"width\": 30\n    }\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                overpack:
                  $ref: '#/components/schemas/Overpack'
              required:
              - overpack
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                properties:
                  overpack:
                    $ref: '#/components/schemas/Overpack'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                validation:
                  summary: Validation error
                  description: The request schema is invalid.
                  value:
                    code: 1000
                    message: '"Validation Error. /overpack/type86:The data (string) must match the type: boolean'
                    status: error
                    errors:
                    - '/overpack/type86:The data (string) must match the type: boolean'
        '401':
          $ref: '#/components/schemas/Unauthorized'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '429':
          $ref: '#/components/schemas/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                internalServerError:
                  summary: Internal Server Error
                  description: Overpack could not be created.
                  value:
                    code: 1252
                    message: Overpack could not be created.
                    errors:
                    - Overpack could not be created.
  /overpacks/{id}:
    get:
      tags:
      - Overpacks
      summary: GET /overpacks/{id}
      description: Retrieves an overpack.
      operationId: getOverpacksById
      security:
      - JWT:
        - read_shipments
      parameters:
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          example: application/pdf
          enum:
          - application/json
          - application/pdf
        description: Optionally download the overpack label.
      - in: query
        name: type
        description: The data stream type if you don't want the overpack details and need the label for the overpack.
        required: false
        deprecated: true
        example: PDF
        schema:
          type: string
          enum:
          - PDF
      - name: id
        in: path
        description: The overpack ID
        required: true
        schema:
          type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Accept: application/json\" \\\n  https://api.boxc.com/v1/overpacks/{id}\n"
      responses:
        '200':
          description: OK. Returns PDF blob if `type=PDF` parameter is used.
          content:
            application/json:
              schema:
                properties:
                  overpack:
                    $ref: '#/components/schemas/Overpack'
            application/pdf:
              type: string
        '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: Overpack not found
                  value:
                    code: 1250
                    message: Overpack not found
                    errors:
                    - Overpack not found
        '429':
          $ref: '#/components/schemas/RateLimit'
    put:
      tags:
      - Overpacks
      summary: PUT /overpacks/{id}
      description: Updates an overpack.
      operationId: updateOverpack
      security:
      - JWT:
        - write_shipments
      parameters:
      - name: id
        in: path
        description: The overpack ID
        required: true
        schema:
          type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X PUT https://api.boxc.com/v1/overpacks/{id} \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"height\": 50,\n    \"length\": 91,\n    \"shipments\": [\n      {\n        \"id\": <YOUR SHIPMENT ID>,\n        \"label_id\": <YOUR LABEL ID>,\n        \"tracking_number\": \"<YOUR TRACKING NUMBER>\"\n      }\n    ],\n    \"weight\": 87.5,\n    \"width\": 30\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Overpack'
      responses:
        '200':
          description: OK. When assigning shipments to an overpack a `overpack.shipments[].error` field will be available when it can't be added but a succcessful response is still returned.
          content:
            application/json:
              schema:
                properties:
                  overpack:
                    $ref: '#/components/schemas/Overpack'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                validation:
                  summary: Validation error
                  description: The request schema is invalid.
                  value:
                    code: 1000
                    message: '"Validation Error. /overpack/type86:The data (string) must match the type: boolean'
                    status: error
                    errors:
                    - '/overpack/type86:The data (string) must match the type: boolean'
                cannotModify:
                  summary: Bad Modify Request
                  description: Overpack is locked
                  value:
                    code: 1251
                    message: Overpack is locked
                    errors:
                    - Overpack is locked
        '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: Overpack not found
                  value:
                    code: 1250
                    message: Overpack not found
                    errors:
                    - Overpack not found
        '429':
          $ref: '#/components/schemas/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                internalServerError:
                  summary: Internal Server Error
                  description: Overpack can't be updated
                  value:
                    code: 1254
                    message: Overpack can't be updated
                    errors:
                    - Overpack can't be updated
    delete:
      tags:
      - Overpacks
      summary: DELETE /overpacks/{id}
      description: Deletes an overpack.
      operationId: deleteOverpack
      security:
      - JWT:
        - write_shipments
      parameters:
      - name: id
        in: path
        description: The overpack ID
        required: true
        schema:
          type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X DELETE https://api.boxc.com/v1/overpacks/{id} \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\"\n"
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                cannotDelete:
                  summary: Bad Request
                  description: Overpack is locked
                  value:
                    code: 1251
                    message: Overpack is locked
                    errors:
                    - Overpack is locked
        '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: Overpack not found
                  value:
                    code: 1250
                    message: Overpack not found
                    errors:
                    - Overpack not found
        '429':
          $ref: '#/components/schemas/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                internalServerError:
                  summary: Internal Server Error
                  description: Overpack can't be deleted
                  value:
                    code: 1253
                    message: Overpack can't be deleted
                    errors:
                    - Overpack can't be deleted
components:
  schemas:
    overpack-list:
      type: object
      properties:
        carrier:
          description: The final mile carrier for this overpack inherited from the shipments.
          type: string
          format: string
          example: USPS
          readOnly: true
        contains_dg:
          description: Indicates the overpack contains a shipment with a dangerous good.
          type: boolean
          example: true
          readOnly: true
        created:
          description: The date and time the overpack was created.
          type: string
          format: datetime
          example: '2024-05-17 15:43:03'
          readOnly: true
        entry_point:
          description: The drop off location for this overpack. See Entry Points for a list of codes. All shipments must have the same entry point. The system determines the entry point based on the shipments.
          type: string
          example: LAXI01
          readOnly: true
        exit_point:
          description: The exit port for this shipment determined by the system. This value is null for shipments where exit port is deemed inconsequential for the destination.
          type: string
          default: null
          example: LAX
          readOnly: true
        external_tracking:
          description: Some carriers require their own tracking numbers to be present on the overpack label.
          type: string
          default: null
          example: null
          readOnly: true
        height:
          description: The height of the overpack in cm.
          type: integer
          example: '50'
        id:
          description: The ID of the overpack.
          type: integer
          example: 12091
          readOnly: true
        length:
          description: The length of the shipment in cm.
          type: integer
          example: 91
        locked:
          description: Whether or not the overpack is locked. Overpacks are locked by the system when they are part of a manifest. They can't be modified once manifested.
          type: boolean
          example: false
          readOnly: true
        manifest_id:
          description: The ID of the manifest this overpack is linked to.
          type: integer
          example: 1010023
          readOnly: true
        pga:
          description: Indicates this overpack contains sensitive materials based on the HTS code(s) and destination country.
          type: boolean
          example: false
          default: false
          readOnly: true
        route_heading:
          type: string
          description: Route heading.
          readOnly: true
          example: DHLeC
        route_subheading:
          type: string
          description: Route subheading.
          readOnly: true
          example: LAX - MAX
        service:
          description: The BoxC service type. All shipments inside this overpack must have the same service. The system determines the service type based on the shipments.
          type: string
          example: BoxC Parcel
          readOnly: true
        terms:
          description: The shipping terms for this overpack inherited from the shipments. All shipments in the overpack must have the same terms.
          type: string
          example: null
          readOnly: true
        total_shipments:
          description: The total number of shipments in the overpack. Only present when getting a list of overpacks.
          type: integer
          example: 432
          readOnly: true
        type86:
          description: Indicates the overpack contains only Type 86 shipments. This will be false for most clients.
          type: boolean
          example: false
          deprecated: true
          readOnly: true
        weight:
          description: The weight of the overpack in KG rounded to 1 significant digit after the decimal point. Required to manifest.
          type: decimal
          example: 87.5
        width:
          description: The width of the overpack in cm.
          type: integer
          example: 30
    internal-server-error:
      type: object
      summary: Internal Server Error
      description: Processing Error
      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
    overpack:
      type: object
      properties:
        carrier:
          description: The final mile carrier for this overpack inherited from the shipments.
          type: string
          example: USPS
          readOnly: true
        contains_dg:
          description: Indicates the overpack contains a shipment with a dangerous good.
          type: boolean
          example: true
          readOnly: true
        created:
          description: The date and time the overpack was created.
          type: string
          format: datetime
          example: '2024-05-17 15:43:03'
          readOnly: true
        entry_point:
          description: The drop off location for this overpack. See Entry Points for a list of codes. All shipments must have the same entry point. The system determines the entry point based on the shipments.
          type: string
          example: LAXI01
          minLength: 3
          maxLength: 3
          readOnly: true
        exit_point:
          description: The exit port for this overpack determined by the system. This value is null for shipments where exit port is deemed inconsequential for the destination.
          type: string
          default: null
          example: LAX
          pattern:
          - A-Z
          minLength: 3
          maxLength: 3
          readOnly: true
        external_tracking:
          description: Some carriers require their own tracking numbers to be present on the overpack label.
          type: string
          default: null
          example: null
          readOnly: true
          maxLength: 40
        height:
          description: The height of the overpack in cm. Required to manifest.
          type: integer
          example: 50
        id:
          description: The ID of the overpack.
          type: integer
          example: 12091
          readOnly: true
        length:
          description: The length of the overpack in cm. Required to manifest.
          type: integer
          example: 91
        locked:
          description: Whether or not the overpack is locked. Overpacks are locked by the system when they are part of a manifest. They can't be modified once manifested.
          type: boolean
          example: false
          readOnly: true
        manifest_id:
          description: The ID of the manifest this overpack is linked to.
          type: integer
          example: 1010023
          readOnly: true
        pga:
          description: Indicates this overpack contains sensitive materials based on the HTS code(s) and destination country.
          type: boolean
          example: false
          default: false
          readOnly: true
        route_heading:
          type: string
          description: Route heading.
          example: null
          readOnly: true
        route_subheading:
          type: string
          description: Route subheading.
          example: null
          readOnly: true
        service:
          description: The BoxC service type. All shipments inside this overpack must have the same service. The system determines the service type based on the shipments.
          type: string
          example: BoxC Parcel
          readOnly: true
        shipments:
          description: 'A list of shipments inside this overpack. Clients should use this to add multiple shipments at once. Only one child attribute is required to add the shipment to the overpack. The system will check for matching shipments in the following order: shipments[].id, shipments[].label_id, or shipments[].tracking_number. Only present when getting or putting a single overpack. At least one shipment is required to determine the routing logic of the overpack. Subsequent shipments'' attributes must match the first one that was added.'
          type: array
          minItems: 1
          items:
            type: object
            properties:
              id:
                description: The shipment ID.
                type: integer
                example: 1212
              label_id:
                description: The label ID.
                type: integer
                example: 781028
              tracking_number:
                type: string
                description: The shipment's tracking number.
                example: '9261299991753900000290'
                maxLength: 40
              error:
                type: string
                description: Error message only present when a shipment can't be assigned to an overpack because of a mismatch of attributes.
                example: Can't mix shipments with different terms
                readOnly: true
            additionalProperties: false
        terms:
          description: The shipping terms for this overpack inherited from the shipments. All shipments in the overpack must have the same terms.
          type: string
          example: null
          readOnly: true
        total_shipments:
          description: The total number of shipments in the overpack. Only present when getting a list of overpacks.
          type: integer
          example: 432
          minimum: 0
          readOnly: true
        type86:
          description: Indicates the overpack contains only Type 86 shipments. This will be false for most clients.
          type: boolean
          example: false
          readOnly: true
          deprecated: true
        weight:
          description: The weight of the overpack in KG rounded to 1 significant digit after the decimal point. Required to manifest.
          type: decimal
          example: 87.5
        width:
          description: The width of the overpack in cm. Required to manifest.
          type: integer
          example: 30
      required:
      - shipments
    RateLimit:
      $ref: '#/components/schemas/rate-limit'
    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'
    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.
    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
    Forbidden:
      $ref: '#/components/schemas/forbidden'
    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
    OverpackList:
      $ref: '#/components/schemas/overpack-list'
    Unauthorized:
      $ref: '#/components/schemas/unauthorized'
    Overpack:
      $ref: '#/components/schemas/overpack'
    InternalServerError:
      $ref: '#/components/schemas/internal-server-error'
    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
    NotFound:
      $ref: '#/components/schemas/not-found'
  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
  - Tr

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boxc/refs/heads/main/openapi/boxc-overpacks-api-openapi.yml