Boxc Reshipments API

swagger: '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.

    '
schemes:
- https
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
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - returns
      parameters:
      - in: query
        name: limit
        description: The number of results to return.
        default: 50
        minimum: 50
        maximum: 100
        required: false
        type: integer
      - in: query
        name: order
        description: The sort order of the results.
        enum:
        - asc
        - desc
        default: desc
        required: false
        type: string
      - in: query
        name: page_token
        description: Used for selecting the page after the initial query.
        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/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: '#/definitions/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: '#/definitions/BadRequest'
              examples:
                invalidToken:
                  summary: Bad Request
                  description: Invalid page token
                  value:
                    code: 1025
                    message: Invalid page token
                    errors:
                    - Invalid page token
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
    post:
      tags:
      - Reshipments
      summary: POST /reshipments
      description: Creates a reshipment.
      operationId: addReshipment
      consumes:
      - application/json
      produces:
      - application/json
      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: '#/definitions/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: '#/definitions/Reshipment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/definitions/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: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/definitions/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
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The reshipment ID
        required: true
        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: '#/definitions/Reshipment'
        '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: Reshipment not found
                  value:
                    code: 1140
                    message: Reshipment not found
                    errors:
                    - Reshipment not found
        '429':
          $ref: '#/definitions/RateLimit'
    put:
      tags:
      - Reshipments
      summary: PUT /reshipments/{id}
      description: Updates a reshipment.
      operationId: updateReshipment
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The reshipment ID
        required: true
        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: '#/definitions/Reshipment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/definitions/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: '#/definitions/Unauthorized'
        '402':
          $ref: '#/definitions/PaymentRequired'
        '403':
          $ref: '#/definitions/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/definitions/NotFound'
              examples:
                notFound:
                  summary: Not Found
                  description: Reshipment not found
                  value:
                    code: 1140
                    message: Reshipment not found
                    errors:
                    - Reshipment not found
        '429':
          $ref: '#/definitions/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/definitions/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
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The reshipment ID
        required: true
        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: '#/definitions/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: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/definitions/NotFound'
              examples:
                notFound:
                  summary: Not Found
                  description: Reshipment not found
                  value:
                    code: 1140
                    message: Reshipment not found
                    errors:
                    - Reshipment not found
        '429':
          $ref: '#/definitions/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/definitions/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
definitions:
  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'
  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
  PaymentRequired:
    $ref: '#/definitions/payment-required'
  InternalServerError:
    $ref: '#/definitions/internal-server-error'
  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
  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
  NotFound:
    $ref: '#/definitions/not-found'
  BadRequest:
    $ref: '#/definitions/bad-request'
  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
  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: '#/definitions/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.
  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
  To:
    $ref: '#/definitions/to'
  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
  Forbidden:
    $ref: '#/definitions/forbidden'
  Unauthorized:
    $ref: '#/definitions/unauthorized'
  RateLimit:
    $ref: '#/definitions/rate-limit'
  Reshipment:
    $ref: '#/definitions/reshipment'
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