Boxc Reshipments API

openapi: 3.2.0
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Reshipments 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: Reshipments
  x-displayName: Reshipments
  description: 'The Reshipments resource allows you to reship one or more returned packages at a time from a BoxC warehouse. When a reshipment is created the `status` of all included returns will change to "Reshipping". Only returns with the following status can be reshipped: Processed, Verifying, and Verified. If reshipping more than one return at a time then you must wait for a facility operator to provide an `estimated_reship_fee`. If reshipping one return then the estimate will be instantaneous. In both cases you must approve the estimate before the reshipment is sent and your account is charged.


    **Note:** All returns in a bulk reshipment (> 1 return) must reside in the same warehouse.

    ### Status

    When a reshipment is created its status is set to "Pending" by default. It will remain that way until the `estimated_reship_fee` is populated by the system or facility operator. Afterwards, you have the option to approve or decline the amount by [updating](/#tag/Reshipments/operation/updateReshipment) the status accordingly. If "Declined", it will not be reshipped. If "Approved" it will be reshipped, tracking information will be made available, and a final reship_fee will be provided. Reshipments with the status "Approved" cannot be deleted.


    **Important:** Reshipments that are "Pending" or "Declined" longer than 15 days will be deleted by the system.


    **Note:** The final reshipping fee may differ from the estimated reshipping fee.'
paths:
  /reshipments:
    get:
      tags:
      - Reshipments
      summary: GET /reshipments
      description: Retrieves a paginated list of reshipments.
      operationId: getReshipments
      security:
      - JWT:
        - returns
      parameters:
      - in: query
        name: limit
        description: The number of results to return.
        required: false
        schema:
          type: integer
          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/reshipments\\?limit=50\\&order=desc\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  reshipments:
                    type: array
                    items:
                      type: object
                      properties:
                        contents:
                          description: A description of the contents in this reshipment for Customs requirements.
                          type: string
                          format: string
                          maxLength: 60
                          default: null
                          example: Leggings
                        created:
                          description: The UTC date and time the reshipment was created. Set by the system.
                          type: string
                          example: '2024-06-27 11:32:18'
                        estimated_reship_fee:
                          description: An estimated price in USD for this reshipment including the cost of the label and packaging material. Set by the system.
                          type: decimal
                          default: 0
                          example: 14.2
                        id:
                          description: The unique ID for this reshipment. Set by the system.
                          type: integer
                          example: 13489
                        reship_fee:
                          description: The fee in USD for this reshipment including the cost of the label and packaging material. Set by the system.
                          type: decimal
                          default: 0
                          example: 14.37
                        returns:
                          type: integer
                          description: The total number of returns included in this reshipment. This property is immutable.
                          example: 3
                        service:
                          description: The carrier used for this reshipment. Set by the system.
                          type: string
                          default: null
                          example: USPS
                        status:
                          type: string
                          description: 'The status of this reshipment. Can be one of:


                            - Pending


                            - Declined


                            - Approved

                            '
                          example: Approved
                        to:
                          $ref: '#/components/schemas/To'
                        tracking_number:
                          type: string
                          description: The tracking number for this reshipment. Set by the system.
                          default: null
                          example: '9261299997140101431920'
                        value:
                          type: decimal
                          description: The total value of the contents in this reshipment for Customs requirements.
                          example: 29.95
                        weight:
                          description: The measured actual weight of this reshipment in KG. Set by the system.
                          type: decimal
                          default: 0
                          example: 0.791
                  next_page:
                    type: string
                    description: Page token
                    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:
      - Reshipments
      summary: POST /reshipments
      description: Creates a reshipment.
      operationId: addReshipment
      security:
      - JWT:
        - returns
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/reshipments \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"reshipment\": {\n      \"contents\": \"Leggings\",\n      \"returns\": [\n        12001,\n        12002\n      ],\n      \"to\": {\n        \"company_name\": null,\n        \"name\": \"John Smith\",\n        \"phone\": \"555-123-4562\",\n        \"email\": \"john@example.com\",\n        \"street1\": \"108 N WESTGATE WAY\",\n        \"street2\": null,\n        \"city\": \"WYLIE\",\n        \"province\": \"TX\",\n        \"postal_code\": \"75098\",\n        \"country\": \"US\"\n      },\n      \"value\": 29.95\n    }\n  }'\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reshipment:
                  type: object
                  properties:
                    contents:
                      description: A description of the contents in this reshipment for Customs requirements.
                      type: string
                      format: string
                      maxLength: 60
                      default: null
                      example: Leggings
                    returns:
                      type: array
                      description: A list of return IDs included in this reshipment. If searching for reshipments then the total number of returns will be shown instead. This property is immutable.
                      items:
                        type: integer
                      example:
                      - 12001
                      - 12002
                    to:
                      $ref: '#/components/schemas/To'
                    value:
                      type: decimal
                      description: The total value of the contents in this reshipment for Customs requirements.
                      example: 29.95
                  required:
                  - contents
                  - value
                  - to
                  - returns
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  reshipment:
                    $ref: '#/components/schemas/Reshipment'
        '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. /reshipment: The required properties (contents) are missing'
                    status: error
                    errors:
                    - '/reshipment: The required properties (contents) are missing'
                badRequest:
                  summary: Bad Request
                  description: Return can't be reshipped
                  value:
                    code: 1144
                    message: Return can't be reshipped
                    status: error
                    errors:
                    - Return can't be reshipped
                badReturnRequest:
                  summary: Return can't be reshipped
                  description: One or more returns can't be reshipped
                  value:
                    code: 1143
                    message: One or more returns can't be reshipped
                    status: error
                    errors:
                    - One or more returns can't be reshipped
        '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: Server error. Try again later.
                  value:
                    code: 1001
                    message: Server error. Try again later.
                    errors:
                    - Server error. Try again later.
  /reshipments/{id}:
    get:
      tags:
      - Reshipments
      summary: GET /reshipments/{id}
      description: Retrieves a reshipment.
      operationId: getReshipmentsById
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The reshipment 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/reshipments/{id}\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  reshipment:
                    $ref: '#/components/schemas/Reshipment'
        '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: Reshipment not found
                  value:
                    code: 1140
                    message: Reshipment not found
                    errors:
                    - Reshipment not found
        '429':
          $ref: '#/components/schemas/RateLimit'
    put:
      tags:
      - Reshipments
      summary: PUT /reshipments/{id}
      description: Updates a reshipment.
      operationId: updateReshipment
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The reshipment ID
        required: true
        schema:
          type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X PUT https://api.boxc.com/v1/reshipments/{id} \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"reshipment\": {\n      \"status\": \"Approved\"\n    }\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reshipment:
                  type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - Declined
                      - Approved
                      description: The status of this reshipment.
                      example: Approved
                  required:
                  - status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  reshipment:
                    $ref: '#/components/schemas/Reshipment'
        '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. /reshipment: The required properties (status) are missing'
                    status: error
                    errors:
                    - '/reshipment: The required properties (status) are missing'
                barcode:
                  summary: Bad Request
                  description: Reshipment can't be updated
                  value:
                    code: 1141
                    message: Reshipment can't be updated
                    errors:
                    - Reshipment can't be updated
        '401':
          $ref: '#/components/schemas/Unauthorized'
        '402':
          $ref: '#/components/schemas/PaymentRequired'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                notFound:
                  summary: Not Found
                  description: Reshipment not found
                  value:
                    code: 1140
                    message: Reshipment not found
                    errors:
                    - Reshipment 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: There was an error while fetching the account balance
                  value:
                    code: 1081
                    message: There was an error while fetching the account balance
                    errors:
                    - There was an error while fetching the account balance
    delete:
      tags:
      - Reshipments
      summary: DELETE /reshipments/{id}
      description: Deletes a reshipment.
      operationId: deleteReshipment
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The reshipment ID
        required: true
        schema:
          type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X DELETE https://api.boxc.com/v1/reshipments/{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: Reshipment can't be deleted
                  value:
                    code: 1142
                    message: Reshipment can't be deleted
                    errors:
                    - Reshipment can't be deleted
        '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: Reshipment not found
                  value:
                    code: 1140
                    message: Reshipment not found
                    errors:
                    - Reshipment 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: Reshipment can't be deleted
                  value:
                    code: 1142
                    message: Reshipment can't be deleted
                    errors:
                    - Reshipment can't be deleted
components:
  schemas:
    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
    reshipment:
      type: object
      properties:
        contents:
          description: A description of the contents in this reshipment for Customs requirements.
          type: string
          format: string
          maxLength: 60
          default: null
          example: Leggings
        created:
          description: The UTC date and time the reshipment was created.
          type: string
          example: '2024-06-27 11:32:18'
          format: datetime
          readOnly: true
        estimated_reship_fee:
          description: An estimated price in USD for this reshipment including the cost of the label and packaging material.
          type: decimal
          default: 0
          example: 14.2
        id:
          description: The unique ID for this reshipment.
          type: integer
          example: 13489
        reship_fee:
          description: The fee in USD for this reshipment including the cost of the label and packaging material.
          type: decimal
          default: 0
          example: 14.37
        returns:
          type: array
          description: A list of return IDs included in this reshipment. If searching for reshipments then the total number of returns will be shown instead. This property is immutable.
          items:
            type: integer
          example:
          - 12001
          - 12002
        service:
          description: The carrier used for this reshipment.
          type: string
          default: null
          example: USPS
        status:
          type: string
          enum:
          - Pending
          - Declined
          - Approved
          description: The status of this reshipment.
          example: Approved
        to:
          $ref: '#/components/schemas/To'
        tracking_number:
          type: string
          description: The tracking number for this reshipment.
          default: null
          example: '9261299997140101431920'
        value:
          type: decimal
          description: The total value of the contents in this reshipment for Customs requirements.
          example: 29.95
        weight:
          description: The measured actual weight of this reshipment in KG.
          type: decimal
          default: 0
          example: 0.791
      required:
      - to
      - contents
      - value
      - returns
      additionalProperties: false
    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.
    NotFound:
      $ref: '#/components/schemas/not-found'
    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'
    Reshipment:
      $ref: '#/components/schemas/reshipment'
    RateLimit:
      $ref: '#/components/schemas/rate-limit'
    To:
      $ref: '#/components/schemas/to'
    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
    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
    Unauthorized:
      $ref: '#/components/schemas/unauthorized'
    InternalServerError:
      $ref: '#/components/schemas/internal-server-error'
    PaymentRequired:
      $ref: '#/components/schemas/payment-required'
    to:
      description: The recipient's shipping address. This may or may not be the same as the consignee. Countries have different formatting rules and element requirements for addresses.
      title: ShippingAddress
      type: object
      properties:
        company_name:
          description: The company name.
          type: string
          maxLength: 40
          default: null
          example: null
        name:
          description: The recipient's name.
          type: string
          maxLength: 40
          example: John Smith
        phone:
          description: The recipient's phone number. Conditional.
          type: string
          default: null
          maxLength: 20
          format: phone
          example: 555-123-4562
        email:
          description: The recipient's e-mail address. Conditional.
          type: string
          default: null
          maxLength: 64
          format: email
          example: john@example.com
        street1:
          description: The recipient's street address.
          type: string
          maxLength: 50
          minLength: 1
          example: 108 N WESTGATE WAY
        street2:
          description: Additional space for the recipient's street address.
          type: string
          maxLength: 50
          default: null
          example: null
        city:
          description: The recipient's city.
          type: string
          maxLength: 40
          example: WYLIE
        province:
          description: The recipient's province or state. Conditional.
          type: string
          maxLength: 40
          default: null
          example: TX
        postal_code:
          description: The recipient's postal code or ZIP Code. Conditional.
          type: string
          maxLength: 10
          default: null
          example: '75098'
        country:
          description: The recipient's country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
          type: string
          pattern:
          - A-Z
          maxLength: 2
          minLength: 2
          example: US
      required:
      - name
      - street1
      - city
      - country
    payment-required:
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            summary: Payment Required
            description: There are insufficient funds available for this 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: Duplicate of the error message
                type: array
                items:
                  type: string
          examples:
            paymentRequired:
              summary: Payment Required
              description: Insufficient funds
              value:
                code: 1080
                message: Insufficient funds
                errors:
                - Insufficient funds
  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:
- n

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