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 Reshipments API
  version: '1.131'
  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.
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 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:
    Reshipment:
      $ref: '#/components/schemas/reshipment'
    NotFound:
      $ref: '#/components/schemas/not-found'
    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'
    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
    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
    internal-server-error:
      type: object
      summary: Internal Server Error
      description: Internal Server 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
    InternalServerError:
      $ref: '#/components/schemas/internal-server-error'
    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
    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: '#/components/schemas/payment-required'
    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
    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
    BadRequest:
      $ref: '#/components/schemas/bad-request'
    Forbidden:
      $ref: '#/components/schemas/forbidden'
    Unauthorized:
      $ref: '#/components/schemas/unauthorized'
    To:
      $ref: '#/components/schemas/to'
  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


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/boxc/openapi/boxc-reshipments-api-openapi.yml