Boxc

Boxc Returns API

The Returns resource allows a user to retrieve a list of returned shipments processed at a BoxC warehouse. Users may verify, [reship](/#tag/Reshipments), or discard their returns. Discarding a return is irreversible. ### Verify Users have the option to verify a return before reshipping it. The facility operator will take additional pictures of the contents inside the return and add messages if necessary. To verify a return the user should PUT a `status` of "Verify". This will change the status of the return to "Verifying" which cannot be reversed. Only returns in the "Processed" state can be verified.

Documentation GitHub OpenAPI

Operations 5

GET /returns GET /returns #

GET /returns/{id} GET /returns/{id} #

PUT /returns/{id} PUT /returns/{id} #

DELETE /returns/{id} DELETE /returns/{id} #

POST /returns/{id}/messages POST /returns/{id}/messages #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/boxc-returns-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Returns 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: Returns
  x-displayName: Returns
  description: 'The Returns resource allows a user to retrieve a list of returned shipments processed at a BoxC warehouse. Users may verify, [reship](/#tag/Reshipments), or discard their returns. Discarding a return is irreversible.

    ### Verify

    Users have the option to verify a return before reshipping it. The facility operator will take additional pictures of the contents inside the return and add messages if necessary. To verify a return the user should <strong>PUT</strong> a `status` of "Verify". This will change the status of the return to "Verifying" which cannot be reversed. Only returns in the "Processed" state can be verified.'
paths:
  /returns:
    get:
      tags:
      - Returns
      summary: GET /returns
      description: Retrieves a paginated list of returns.
      operationId: getReturns
      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
      - in: query
        name: tracking_number
        description: Filter that selects returns with the given tracking_number. Default behavior is to return all returns.
        required: false
        schema:
          type: string
          default: null
      - in: query
        name: status
        description: Filter that selects returns with the given status. Default behavior is to return all returns.
        required: false
        schema:
          type: string
          default: null
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Accept: application/json\" \\\n  https://api.boxc.com/v1/returns\\?limit=50\\&order=desc\\&status=Processed\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  returns:
                    type: array
                    items:
                      type: object
                      properties:
                        created:
                          description: The UTC date and time the return was processed at a facility.
                          type: string
                          example: '2024-06-27 11:32:18'
                          readOnly: true
                        id:
                          description: The unique ID for this return.
                          type: integer
                          example: 13489
                          readOnly: true
                        messages:
                          type: integer
                          description: The number of messages.
                          example: 2
                          readOnly: true
                        process_fee:
                          description: The fee in USD for processing this return.
                          type: decimal
                          example: 1
                          readOnly: true
                        reshipment_id:
                          description: The unique ID for this return's reshipment if available.
                          type: integer
                          default: null
                          example: 102910
                          readOnly: true
                        rma_number:
                          type: string
                          description: The return merchandise authorization (RMA) for this return if available.
                          default: null
                          example: RMA10293021
                        status:
                          type: string
                          enum:
                          - Processed
                          - Verifying
                          - Verified
                          - Reshipping
                          - Reshipped
                          description: 'The status of the return.

                            '
                          example: Processed
                          readOnly: true
                        tracking_number:
                          type: string
                          description: The tracking number that was used by the sender for this return.
                          example: '9261299997140101431920'
                          readOnly: true
                        verify_fee:
                          description: The fee in USD for verifying this return. Only applies to returns that were verified.
                          type: decimal
                          default: 0
                          example: 0
                          readOnly: true
                        warehouse:
                          description: Information about the warehouse the return was processed at.
                          type: object
                          properties:
                            id:
                              description: The warehouse id
                              type: string
                              example: WH0CVG01
                              readOnly: true
                        weight:
                          description: The measured weight of this return in KG.
                          type: decimal
                          default: 0
                          example: 0.128
                          readOnly: true
                  next_page:
                    type: string
                    description: Page token. Set by the system.
                    example: ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZsYXN0X2lkPTE1Mzg0Nw
                    readOnly: true
        '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'
  /returns/{id}:
    get:
      tags:
      - Returns
      summary: GET /returns/{id}
      description: Retrieves a return.
      operationId: getReturnsById
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The return 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/returns/{id}\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  return:
                    $ref: '#/components/schemas/Return'
        '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: Return not found
                  value:
                    code: 1120
                    message: Return not found
                    errors:
                    - Return not found
        '429':
          $ref: '#/components/schemas/RateLimit'
    put:
      tags:
      - Returns
      summary: PUT /returns/{id}
      description: Request verification of a return.
      operationId: updateReturn
      security:
      - JWT:
        - returns
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X PUT https://api.boxc.com/v1/returns/{id} \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"return\": {\n      \"status\": \"Verify\"\n    }\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                return:
                  type: object
                  properties:
                    status:
                      type: string
                      description: Change the status to Verify.
                      example: Verify
                      enum:
                      - Verify
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  return:
                    $ref: '#/components/schemas/Return'
        '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. /return: The required properties (status) are missing'
                    status: error
                    errors:
                    - '/return: The required properties (status) are missing'
                badRequest:
                  summary: Bad Request
                  description: Return must be processed before verifying
                  value:
                    code: 1121
                    message: Return must be processed before verifying
                    errors:
                    - Return must be processed before verifying
        '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: Return not found
                  value:
                    code: 1120
                    message: Return not found
                    errors:
                    - Return 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
                chargingError:
                  summary: Internal Server Error - Charging Account
                  description: There was an error while charging the account balance
                  value:
                    code: 1082
                    message: There was an error while charging the account balance
                    errors:
                    - There was an error while charging the account balance
    delete:
      tags:
      - Returns
      summary: DELETE /returns/{id}
      description: Deletes a return.
      operationId: deleteReturn
      security:
      - JWT:
        - returns
      parameters:
      - name: id
        in: path
        description: The return ID
        required: true
        schema:
          type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X DELETE https://api.boxc.com/v1/returns/{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: Return can't be discarded with this status
                  value:
                    code: 1122
                    message: Return can't be discarded
                    errors:
                    - Return can't be discarded
        '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: Return not found
                  value:
                    code: 1120
                    message: Return not found
                    errors:
                    - Return not found
        '429':
          $ref: '#/components/schemas/RateLimit'
  /returns/{id}/messages:
    post:
      tags:
      - Returns
      summary: POST /returns/{id}/messages
      description: Adds a message to a return.
      operationId: addReturn
      security:
      - JWT:
        - returns
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/returns/{id}/messages \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"message\": {\n      \"body\": \"Forward to John Doe, Order ID #123458-10\"\n    }\n  }'\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: object
                  properties:
                    body:
                      type: string
                      description: The content body of the message.
                      example: 'Forward to John Doe, Order ID #123458-10'
                      maxLength: 200
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  return:
                    $ref: '#/components/schemas/Return'
        '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. /return: The required properties (body) are missing'
                    status: error
                    errors:
                    - '/return: The required properties (body) are missing'
        '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: Return not found
                  value:
                    code: 1120
                    message: Return not found
                    errors:
                    - Return not found
        '429':
          $ref: '#/components/schemas/RateLimit'
components:
  schemas:
    Message:
      $ref: '#/components/schemas/message'
    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
    Return:
      $ref: '#/components/schemas/return'
    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'
    RateLimit:
      $ref: '#/components/schemas/rate-limit'
    message:
      type: object
      properties:
        author:
          description: The creator of the message. Can be either "user" or "operator".
          type: string
          example: user
          readOnly: true
        body:
          description: The content body of the message.
          type: string
          maxLength: 200
          example: Please handle with care
        created:
          description: The UTC date and time the message was created.
          type: string
          example: '2024-06-20 10:11:12'
          readOnly: true
        id:
          description: The unique ID for this message.
          type: integer
          example: 40119
          readOnly: true
    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'
    return:
      type: object
      properties:
        created:
          description: The UTC date and time the return was processed at a facility.
          type: string
          example: '2024-06-27 11:32:18'
          format: datetime
          readOnly: true
        id:
          description: The unique ID for this return.
          type: integer
          example: 13489
          readOnly: true
        images:
          type: array
          description: A list of images taken for this return. Only present when retrieving a single return. Images are removed when the return is discarded.
          readOnly: true
          items: string
          example:
          - https://api.boxc.com/i/32e186166912f18072645e793933904a115f23ce3d33108853640d1d3f94c6b6.jpg
          - https://api.boxc.com/i/032b960ff67c0fe830e78cb60a2a1b09df18c216a15cacddfbcbfaed33da473e.jpg
        messages:
          type: array
          description: A list of message objects left by the user or operater for this return. Messages are sorted by created in descending order. If searching, the number of messages will be returned instead. See message for details about each property.
          items:
            messages:
              $ref: '#/components/schemas/Message'
        process_fee:
          description: The fee in USD for processing this return.
          type: decimal
          example: 1
          readOnly: true
        reshipment_id:
          description: The unique ID for this return's reshipment if available.
          type: integer
          default: null
          example: 102910
          readOnly: true
        rma_number:
          type: string
          description: The return merchandise authorization (RMA) for this return if available.
          default: null
          example: RMA10293021
          readOnly: true
        status:
          type: string
          enum:
          - Processed
          - Verifying
          - Verified
          - Reshipping
          - Reshipped
          description: The status of the return.
          example: Processed
        tracking_number:
          type: string
          description: The tracking number that was used by the sender for this return.
          example: '9261299997140101431920'
          readOnly: true
        verify_fee:
          description: The fee in USD for verifying this return. Only applies to returns that were verified.
          type: decimal
          default: 0
          example: 0
          readOnly: true
        warehouse:
          description: Information about the warehouse the return was processed at.
          type: object
          properties:
            id:
              description: The warehouse id
              type: string
              example: WH0CVG01
              readOnly: true
        weight:
          description: The measured weight of this return in KG.
          type: decimal
          default: 0
          example: 0.128
          readOnly: true
    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'
    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:
- 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