swagger: '2.0'
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Orders 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: Orders
  x-displayName: Orders
  description: 'The Orders resource allows you to create, read, update, and delete orders that are meant to be fulfilled by BoxC. If you wish to manually create an order for a third party shop you must provide the `shop.id` and `shop.order_id`. Neither property can be updated. The system will push tracking information to the shop when the order is fulfilled if both properties are set. Clients can force which warehouse is used for order fulfillment by setting the `warehouse.id` property.

    ### Order Status


    The following table lists all possible states of an order indicated by its `status` property. Updating an order that is ''Ready'' will reset its status to ''Processing'' and restore product quantities until it''s processed by the system again.


    | Status | Description |

    |--------|-------------|

    | Backordered | There is insufficient quantity for one or more line items. The system will change the status once more inventory is added. |

    | Exception | There is a problem with the order such as missing or invalid information. The user must correct the problem before the order can be processed by the system. |

    | Holding | The order is being delayed from processing by the user. |

    | Processing | The order is waiting for the system to process it. Default state. |

    | Ready | The order is assigned to a warehouse for packing and quantities were deducted. |

    | Packing | One or more line items are being packed. <em>It can''t be edited in this state</em>. |

    | Partial | The order was partially fulfilled. The remaining line items will be fulfilled when more inventory arrives. |

    | Fulfilled | The order was completely fulfilled. |

    | Archived | The system archives orders that were fulfilled at least 90 days in the past. |


    ### Pruning Orders


    The system routinely prunes or closes out orders in the system more than **365 days** ago. The start time is based on the `placed_at` and not the `created` datetime. What happens to the order depends on its current state at the time of pruning.


    - Unfulfilled (not Packing, Partial, Fulfilled) orders are deleted.

    - Partially fulfilled orders (Holding, Packing, Partial) are bumped to Fulfilled.

    - Orders in Packing have their unfulfilled line items and fulfillment objects deleted, and are bumped to Fulfilled.

    '
paths:
  /orders:
    get:
      tags:
      - Orders
      summary: GET /orders
      description: Retrieves a paginated list of orders.
      operationId: getOrders
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - read_orders
      parameters:
      - in: query
        name: created_min
        description: The inclusive date to begin the search in YYYY-MM-DD format.
        required: false
        default: null
        type: string
      - in: query
        name: created_max
        description: The inclusive date to end the search in YYYY-MM-DD format.
        required: false
        type: string
        default: null
      - in: query
        name: limit
        description: The number of results to return.
        required: false
        type: integer
        default: 50
        minimum: 50
        maximum: 100
      - in: query
        name: order
        description: The sort order of the results.
        required: false
        type: string
        default: desc
        enum:
        - asc
        - desc
      - in: query
        name: page_token
        description: Used for selecting the page after the initial query.
        required: false
        type: string
      - in: query
        name: product.id
        description: Filter to return only orders containing the matching product.
        required: false
        type: integer
      - in: query
        name: shipping_address.name
        description: Filter to return only orders matching the shipping addressee's name.
        required: false
        type: string
      - in: query
        name: shop.id
        description: Filter to return only orders belonging to a particular shop you own.
        required: false
        type: string
      - in: query
        name: shop.order_id
        description: Filter to return only orders with a matching shop order ID.
        required: false
        type: string
      - in: query
        name: status
        description: Filter to return only orders with a particular status. Returns all by default.
        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/orders\\?limit=50\\&order=desc\\&status=Processing\\&shop.id=\\&shop.order_id=\\&shipping_address.name=\\&product.id=\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/definitions/Order'
                  next_page:
                    type: string
                    description: Page token. Set by the system.
                    example: ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZsYXN0X2lkPTE1Mzg0Nw
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/definitions/BadRequest'
              examples:
                invalidToken:
                  summary: Bad Request Page Token
                  description: Invalid page token
                  value:
                    code: 1025
                    message: Invalid page token
                    errors:
                    - Invalid page token
                invalidParameter:
                  summary: Bad Request Query Parameter
                  description: Query parameter is invalid
                  value:
                    code: 1031
                    message: Invalid query parameter
                    errors:
                    - Invalid query parameter
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
    post:
      tags:
      - Orders
      summary: POST /orders
      description: Creates an order.
      operationId: addOrder
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - write_orders
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/orders \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"order\": {\n      \"consignee\": {\n        \"name\": \"Addressee John\",\n        \"phone\": \"555-444-7890\",\n        \"email\": null,\n        \"id\": null,\n        \"street1\": \"2959 ANCHOR DR\",\n        \"street2\": null,\n        \"city\": \"MESQUITE\",\n        \"province\": \"TX\",\n        \"postal_code\": 75150,\n        \"country\": \"US\"\n      },\n      \"consignor\": {\n        \"name\": \"Generic Company, LLC\",\n        \"phone\": \"555-123-4567\",\n        \"email\": null,\n        \"id\": null,\n        \"street1\": \"1 WORLD WAY\",\n        \"street2\": \"\",\n        \"city\": \"SHENZHEN\",\n        \"province\": \"GUANGDONG\",\n        \"postal_code\": 518000,\n        \"country\": \"CN\"\n      },\n      \"created\": \"2024-11-17 15:43:03\",\n      \"exception_on_failure\": false,\n      \"from\": {\n        \"name\": \"My Company Name\",\n        \"street1\": \"113 INTL BROADWAY\",\n        \"street2\": \"\",\n        \"city\": \"LOS ANGELES\",\n        \"province\": \"CA\",\n        \"postal_code\": \"91013\",\n        \"country\": \"US\"\n      },\n      \"gift_message\": \"Thanks for the laughs. -Sansa\",\n      \"ignore_bad_address\": false,\n      \"insurance\": false,\n      \"line_items\": [\n        {\n          \"quantity\": 1,\n          \"sku\": \"<PRODUCT SKU>\",\n          \"sold_for\": 9.95\n        }\n      ],\n      \"packing_slip\": true,\n      \"partial_fulfillment\": false,\n      \"service\": \"BoxC Priority\",\n      \"shop\": {\n        \"id\": \"<YOUR SHOP ID>\",\n        \"order_id\": <YOUR ORDER ID>\n      },\n      \"signature_confirmation\": false,\n      \"status\": \"Processing\",\n      \"terms\": \"DDU\",\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      \"warehouse\": {\n        \"id\": \"WH0SZ001\"\n      },\n      \"wholesale\": false\n    }\n  }'\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                order:
                  $ref: '#/definitions/Order'
              required:
              - order
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/definitions/Order'
        '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: Request is malformed.
                    status: error
                    errors:
                    - Request is malformed.
                badRequest:
                  summary: Bad Request Inactive Shop
                  description: Shop is inactive
                  value:
                    code: 1374
                    message: Shop is inactive
                    errors:
                    - Shop is inactive
                missingShop:
                  summary: Bad Shop Request
                  description: Shop not found
                  value:
                    code: 1370
                    message: Shop not found
                    errors:
                    - Shop not found
                badOrderID:
                  summary: Bad Request Order ID
                  description: Duplicate shop.order_id
                  value:
                    code: 1326
                    message: Duplicate shop.order_id
                    errors:
                    - Duplicate shop.order_id
                giftMessage:
                  summary: Bad Request Gift Message
                  description: Packing slip is required for a gift message
                  value:
                    code: 1340
                    message: Packing slip is required for a gift message
                    errors:
                    - Packing slip is required for a gift message
                lineItems:
                  summary: Bad Request Line Items
                  description: Line items in the order must be unique
                  value:
                    code: 1325
                    message: Line items in the order must be unique
                    errors:
                    - Line items in the order must be unique
                addressError:
                  summary: Bad Address Request
                  description: Address Error
                  value:
                    code: 1012
                    message: Address Error
                    errors:
                    - Address Error
                missingSku:
                  summary: Bad Request Missing SKU
                  description: SKU does not exist in Shop
                  value:
                    code: 1330
                    message: SKU does not exist in Shop
                    errors:
                    - SKU does not exist in Shop
                inactiveSku:
                  summary: Bad Request Inactive SKU
                  description: SKU is inactive
                  value:
                    code: 1331
                    message: SKU is inactive
                    errors:
                    - SKU is inactive
                packaging:
                  summary: Bad Request Packaging
                  description: Packaging is not allowed in orders
                  value:
                    code: 1341
                    message: Packaging is not allowed in orders
                    errors:
                    - Packaging is not allowed in orders
        '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: Order could not be created.
                  value:
                    code: 1323
                    message: Order could not be created.
                    errors:
                    - Order could not be created.
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/definitions/ServiceUnavailable'
              examples:
                internalServerError:
                  summary: Service Unavailable
                  description: Address resolution service unavailable at this time.
                  value:
                    code: 503
                    message: Address resolution service unavailable at this time.
                    errors:
                    - Address resolution service unavailable at this time.
  /orders/{id}:
    get:
      tags:
      - Orders
      summary: GET /orders/{id}
      description: Retrieves an order.
      operationId: getOrdersById
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - read_orders
      parameters:
      - name: id
        in: path
        description: The order 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/orders/{id}\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/definitions/Order'
        '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: Order not found
                  value:
                    code: 1320
                    message: Order not found
                    errors:
                    - Order not found
        '429':
          $ref: '#/definitions/RateLimit'
    put:
      tags:
      - Orders
      summary: PUT /orders/{id}
      description: Updates an order.
      operationId: updateOrder
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - write_orders
      parameters:
      - name: id
        in: path
        description: The order ID
        required: true
        type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X PUT https://api.boxc.com/v1/orders/{id} \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"order\": {\n      \"consignee\": {\n        \"name\": \"Addressee John\",\n        \"phone\": \"555-456-7890\",\n        \"email\": null,\n        \"id\": null,\n        \"street1\": \"2959 ANCHOR DR\",\n        \"street2\": null,\n        \"city\": \"MESQUITE\",\n        \"province\": \"TX\",\n        \"postal_code\": 75150,\n        \"country\": \"US\"\n      },\n      \"consignor\": {\n        \"name\": \"Generic Company, LLC\",\n        \"phone\": \"555-123-4567\",\n        \"email\": null,\n        \"id\": null,\n        \"street1\": \"1 WORLD WAY\",\n        \"street2\": \"\",\n        \"city\": \"SHENZHEN\",\n        \"province\": \"GUANGDONG\",\n        \"postal_code\": 518000,\n        \"country\": \"CN\"\n      },\n      \"from\": {\n        \"name\": \"My Company Name\",\n        \"street1\": \"113 INTL BROADWAY\",\n        \"street2\": \"\",\n        \"city\": \"LOS ANGELES\",\n        \"province\": \"CA\",\n        \"postal_code\": \"91013\",\n        \"country\": \"US\"\n      },\n      \"gift_message\": \"Thanks for the laughs. -Sansa\",\n      \"ignore_bad_address\": false,\n      \"insurance\": false,\n      \"line_items\": [\n        {\n          \"quantity\": 1,\n          \"sku\": \"<PRODUCT SKU>\",\n          \"sold_for\": 9.95\n        }\n      ],\n      \"packing_slip\": true,\n      \"partial_fulfillment\": false,\n      \"service\": \"BoxC Priority\",\n      \"shop\": {\n        \"id\": \"<YOUR SHOP ID>\",\n        \"name\": \"Appleseeds\",\n        \"order_id\": <YOUR ORDER ID>,\n        \"type\": \"BoxC\"\n      },\n      \"signature_confirmation\": false,\n      \"status\": \"Processing\",\n      \"terms\": \"DDU\",\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      \"warehouse\": {\n        \"id\": \"WH0SZ001\"\n      },\n      \"wholesale\": false\n    }\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                order:
                  type: object
                  properties:
                    consignee:
                      $ref: '#/definitions/Consignee'
                    consignor:
                      $ref: '#/definitions/Consignor'
                    from:
                      $ref: '#/definitions/From'
                    gift_message:
                      type: string
                      description: An optional message to be included on the packing slip if requested. ``` packing_slip ``` must be true.
                      maxLength: 128
                      example: Thanks for the laughs. -Sansa
                    ignore_bad_address:
                      type: boolean
                      description: Ignore shipping address verification errors. Setting this to true automatically declines insurance coverage unless the shipping address was valid, in which case the system will change this back to false. BoxC Priority addresses can't be ignored.
                      default: false
                      example: false
                    insurance:
                      type: boolean
                      description: Adds more insurance to shipments for a fee based on a percentage of the total value (including shipping cost) of the items in the fulfillment. By default shipments include insurance that covers up to $30 in total value even when insurance is false. Insurance is not available for the BoxC Post service and some accounts.
                      default: false
                      example: false
                    line_items:
                      description: An array of line items belonging to this order. Not all properties are present when searching.
                      type: array
                      items:
                        $ref: '#/definitions/OrderLineItem'
                    packing_slip:
                      type: boolean
                      description: Whether or not this order requires a packing slip for each fulfillment for an additional fee.
                      default: false
                      example: false
                    partial_fulfillment:
                      type: boolean
                      description: Whether or not this order should be fulfilled partially. If true, the warehouse will fulfill line items as their products arrive in the event there is insufficient quantity. This property can't be changed for orders that have already been partially fulfilled.
                      example: false
                    service:
                      type: string
                      description: The type of shipping service you want to use for this shipment. Not all services exist to all countries. If the selected service does not exist, the service will automatically be downgraded to the next available level of service.
                      enum:
                      - BoxC Post
                      - BoxC Parcel
                      - BoxC Plus
                      - BoxC Priority
                      default: BoxC Parcel
                      example: BoxC Priority
                    shop:
                      type: object
                      description: Information about the shop this order is linked to. Required. This object is immutable.
                      properties:
                        id:
                          type: string
                          description: The shop ID.
                          example: my-shop
                        name:
                          type: string
                          description: A user defined shop name.
                          maxLength: 32
                          example: Appleseeds
                        order_id:
                          type: string
                          description: The shop order ID if available. Not required. You must provide this for the system to push tracking information to the third party shop. Must be unique for the shop.
                          maxLength: 32
                          example: 30338272
                        type:
                          type: string
                          description: The shop type. Set by the system.
                          example: BoxC
                      required:
                      - id
                    signature_confirmation:
                      type: boolean
                      description: Request signature confirmation from the recipient upon delivery. Not available for all services or routes. An additional fee may apply.
                      default: false
                      example: false
                    status:
                      type: string
                      description: The order's current status. You may place an order in Holding to prevent fulfillment or Processing to fulfill the order.
                      enum:
                      - Holding
                      - Processing
                      example: Processing
                    terms:
                      description: The [Incoterms](https://en.wikipedia.org/wiki/Incoterms) for this shipment that affects which routes are available. If terms is not provided then the system will pick DDU or DDP if DDU is not available. DDP shipments will include tax and duty.
                      type: string
                      enum:
                      - DAP
                      - DDU
                      - DDP
                      default: DDU
                      example: DDU
                    to:
                      $ref: '#/definitions/To'
                    warehouse:
                      type: object
                      description: Declare the warehouse where you want this order fulfilled. It will not be fulfilled until sufficient quantity exists at the specified warehouse. View the [Warehouses resource](/#tag/Warehouses) for a list. Optional.
                      properties:
                        id:
                          type: string
                          description: The unique warehouse ID. Default is null which is default system behavior.
                          default: null
                          example: WH0SZ001
                      required:
                      - id
                    wholesale:
                      type: boolean
                      description: Indicates this order is for wholesale.
                      default: false
                      example: true
              required:
              - to
              - consignor
              - service
              - line_items
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/definitions/Order'
        '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: Request is malformed.
                    status: error
                    errors:
                    - Request is malformed.
                cannotModify:
                  summary: Bad Modify Request
                  description: Order can't be modified in its current state
                  value:
                    code: 1321
                    message: Order can't be modified in its current state
                    errors:
                    - Order can't be modified in its current state
                giftMessage:
                  summary: Bad Request Gift Message
                  description: Packing slip is required for a gift message
                  value:
                    code: 1340
                    message: Packing slip is required for a gift message
                    errors:
                    - Packing slip is required for a gift message
                lineItems:
                  summary: Bad Request Line Items
                  description: Line items in the order must be unique
                  value:
                    code: 1325
                    message: Line items in the order must be unique
                    errors:
                    - Line items in the order must be unique
                packaging:
                  summary: Bad Request Packaging
                  description: Packaging is not allowed in orders
                  value:
                    code: 1341
                    message: Packaging is not allowed in orders
                    errors:
                    - Packaging is not allowed in orders
                inactiveSku:
                  summary: Bad Request Inactive SKU
                  description: SKU is inactive
                  value:
                    code: 1331
                    message: SKU is inactive
                    errors:
                    - SKU is inactive
                missingSku:
                  summary: Bad Request Missing SKU
                  description: SKU does not exist in Shop
                  value:
                    code: 1330
                    message: SKU does not exist in Shop
                    errors:
                    - SKU does not exist in Shop
                address:
                  summary: Bad Request Address Error
                  description: Address Error
                  value:
                    code: 1012
                    message: Address Error
                    errors:
                    - Address Error
        '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: Order not found
                  value:
                    code: 1320
                    message: Order not found
                    errors:
                    - Order 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: Order could not be updated
                  value:
                    code: 1324
                    message: Order could not be updated
                    errors:
                    - Order could not be updated
    delete:
      tags:
      - Orders
      summary: DELETE /orders/{id}
      description: Deletes an order.
      operationId: deleteOrder
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - write_orders
      parameters:
      - name: id
        in: path
        description: The order ID
        required: true
        type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X DELETE https://api.boxc.com/v1/orders/{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:
                cannotModify:
                  summary: Bad Modify Request
                  description: Order can't be modified in its current state
                  value:
                    code: 1321
                    message: Order can't be modified in its current state
                    errors:
                    - Order can't be modified in its current state
                cannotDelete:
                  summary: Bad Delete Request
                  description: Order can't be deleted
                  value:
                    code: 1322
                    message: Order can't be deleted
                    errors:
                    - Order 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: Order not found
                  value:
                    code: 1320
                    message: Order not found
                    errors:
                    - Order not found
        '429':
          $ref: '#/definitions/RateLimit'
  /orders/status:
    post:
      tags:
      - Orders
      summary: POST /orders/status
      description: Change the status of up to 100 orders at once. Returns the affected orders with their new status including those that can't be changed. It omits orders that can't be found.
      operationId: updateOrderStatus
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - write_orders
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/orders/status \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"orders\": [\n      {\n        \"id\": <YOUR ORDER ID>,\n        \"status\": \"Processing\"\n      }\n    ]\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                orders:
                  type: array
                  items:
                    type: object
                    minItems: 1
                    maxItems: 100
                    properties:
                      id:
                        type: integer
                        description: The order ID.
                        example: 1029210
                      status:
                        type: string
                        description: You may place an order in Holding to prevent fulfillment, or Processing to fulfill the order.
                        enum:
                        - Holding
                        - Processing
                        example: Processing
                    required:
                    - id
                    - status
              required:
              - orders
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/definitions/Order'
        '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. /orders: The required properties (status) are missing'
                    status: error
                    errors:
                    - '/orders: The required properties (status) are missing'
                cannotModify:
                  summary: Bad Modify Request
                  description: Order can't be modified in its current state
                  value:
                    code: 1321
                    message: Order can't be modified in its current state
                    errors:
                    - Order can't be modified in its current state
                notFound:
                  summary: Not Found
                  description: Order not found
                  value:
                    code: 1320
                    message: Order not found
                    errors:
                    - Order not found
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
definitions:
  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
  From:
    $ref: '#/definitions/from'
  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'
  To:
    $ref: '#/definitions/to'
  Consignee:
    $ref: '#/definitions/consignee'
  RateLimit:
    $ref: '#/definitions/rate-limit'
  consignee:
    description: Details about the consignee / buyer. The system will use the shipping address as the consignee address if one isn't provided. Some countries require a tax / passport ID from the buyer.
    type: object
    properties:
      name:
        description: The consignee's name.
        type: string
        maxLength: 40
        example: Addressee John
      phone:
        description: The consignee's phone number. Conditional.
        type: string
        maxLength: 20
        example: 555-456-7890
      email:
        description: The consignee's email address. Conditional.
        type: string
        maxLength: 64
        example: null
      id:
        description: The consignee's Tax ID, GSTIN, Passport, ABN, Vendor ID, etc. Conditional.
        type: string
        maxLength: 20
        example: null
      street1:
        description: The consignee's street address.
        type: string
        maxLength: 50
        example: 2959 ANCHOR DR
      street2:
        description: Additional space for the consignee's street address such as apartment, condo, or unit number.
        type: string
        maxLength: 50
        example: null
      city:
        description: The consignee's city.
        type: string
        maxLength: 40
        example: MESQUITE
      province:
        description: The consignee's province or state code. Conditional.
        type: string
        maxLength: 40
        example: TX
      postal_code:
        description: The consignee's postal code. Conditional.
        type: string
        maxLength: 10
        example: 75150
      country:
        description: The consignee's country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
        type: string
        maxLength: 2
        example: US
    required:
    - name
    - city
    - country
    - street1
  Consignor:
    $ref: '#/definitions/consignor'
  Order:
    $ref: '#/definitions/order'
  OrderLineItem:
    $ref: '#/definitions/order-line-item'
  BadRequest:
    $ref: '#/definitions/bad-request'
  Fulfillment:
    $ref: '#/definitions/fulfillment'
  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.
  order-line-item:
    type: object
    properties:
      dg_code:
        description: The Dangerous Goods code for the product if applicable.
        type: string
        default: null
        example: null
        readOnly: true
      fulfilled:
        description: Whether or not this line item was fulfilled.
        type: boolean
        default: false
        example: false
        readOnly: true
      fulfillment_id:
        description: The fulfillment ID created to fulfill this line item.
        type: integer
        example: 123456
        readOnly: true
      hs_code:
        description: The HS code for the line item if applicable.
        type: string
        default: null
        example: null
        readOnly: true
      name:
        description: The product name.
        type: string
        example: XL T-Shirt
        readOnly: true
      product_id:
        description: The product ID.
        type: integer
        example: 1001181
        readOnly: true
      quantity:
        description: The product quantity that needs to be fulfilled.
        type: integer
        maximum: 9999
        minimum: 1
        example: 1
      sku:
        description: The product SKU belonging to the order's shop.
        type: string
        example: '92820183446'
        minLength: 3
        maxLength: 32
        pattern: A-Za-z0-9-_\s/
      sold_for:
        description: Allows the user to override the product's retail value in case the line item was sold for a different price. This property represents the total value for the line item.
        type: decimal
        default: null
        example: 9.95
    required:
    - quantity
    - sku
  consignor:
    description: Address and other details for the consignor (sender) which is used for customs clearance.
    type: object
    properties:
      name:
        description: The consignor's name.
        type: string
        maxLength: 40
        example: Generic Company, LLC
      phone:
        description: The consignor's phone number.
        type: string
        maxLength: 20
        example: 555-123-4567
      email:
        description: The consignor's email address. Conditional.
        type: string
        maxLength: 64
        default: null
        example: null
      id:
        description: The consignor's Tax ID, GSTIN, Passport, ABN, Vendor ID, etc. Conditional.
        type: string
        maxLength: 20
        example: null
      street1:
        description: The consignor's street address.
        type: string
        maxLength: 50
        example: 1 WORLD WAY
      street2:
        description: Additional space for the consignor's street address such as apartment, condo, or unit number.
        type: string
        maxLength: 50
        example: ''
      city:
        description: The consignor's city.
        type: string
        maxLength: 40
        example: SHENZHEN
      province:
        description: The consignor's province or state code. Conditional.
        type: string
        maxLength: 40
        example: GUANGDONG
      postal_code:
        description: The consignor's postal code. Conditional.
        type: string
        maxLength: 10
        example: 518000
      country:
        description: The consignor's country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
        type: string
        maxLength: 2
        example: CN
    required:
    - name
    - phone
    - street1
    - city
    - country
  order:
    type: object
    properties:
      consignee:
        $ref: '#/definitions/Consignee'
      consignor:
        $ref: '#/definitions/Consignor'
      created:
        description: The date and time the order was created in a third party shop if provided. Otherwise, the date and time the order was created in BoxC. This property is optional and immutable.
        type: string
        example: '2024-06-17 15:43:03'
        format: datetime
      exception_on_failure:
        type: boolean
        description: If true then the order will be created and placed in the "Exception" state when there are address or routing errors.
        default: false
        example: false
        writeOnly: true
      from:
        $ref: '#/definitions/From'
      fulfillments:
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/Fulfillment'
      gift_message:
        type: string
        default: null
        description: An optional message to be included on the packing slip if requested. ``` packing_slip ``` must be true.
        maxLength: 128
        example: Thanks for the laughs. -Sansa
      id:
        type: integer
        description: The order ID
        example: 1029210
        readOnly: true
      ignore_bad_address:
        type: boolean
        description: Ignore shipping address verification errors. Setting this to true automatically declines insurance coverage unless the shipping address was valid, in which case the system will change this back to false. BoxC Priority addresses can't be ignored.
        default: false
        example: false
      insurance:
        type: boolean
        description: Adds more insurance to shipments for a fee based on a percentage of the total value (including shipping cost) of the items in the fulfillment. By default shipments include insurance that covers up to $30 in total value even when insurance is false. Insurance is not available for the BoxC Post service and some accounts.
        default: false
        example: false
      line_items:
        description: An array of line items belonging to this order. Not all properties are present when searching.
        type: array
        items:
          $ref: '#/definitions/OrderLineItem'
      packing_slip:
        type: boolean
        description: Whether or not this order requires a packing slip for each fulfillment for an additional fee.
        default: false
        example: true
      partial_fulfillment:
        type: boolean
        description: Whether or not this order should be fulfilled partially. If true, the warehouse will fulfill line items as their products arrive in the event there is insufficient quantity. This property can't be changed for orders that have already been partially fulfilled.
        example: false
      placed_at:
        description: The date and time (UTC) the order was created in the BoxC system.
        type: string
        example: '2024-06-17 15:43:03'
        format: datetime
        readOnly: true
      products:
        type: integer
        description: The total number of unique products in this order.
        example: 2
        readOnly: true
      quantity:
        type: integer
        description: The total number of items in this order.
        example: 3
        readOnly: true
      service:
        type: string
        description: The type of shipping service you want to use for this shipment. Not all services exist to all countries. If the selected service does not exist, the service will automatically be downgraded to the next available level of service.
        default: BoxC Parcel
        example: BoxC Priority
      shop:
        type: object
        description: Information about the shop this order is linked to. Required. This object is immutable.
        properties:
          id:
            type: string
            description: The shop ID.
            example: my-shop
          name:
            type: string
            description: A user defined shop name.
            maxLength: 32
            example: Appleseeds
            readOnly: true
          order_id:
            type: string
            description: The shop order ID if available. Not required. You must provide this for the system to push tracking information to the third party shop. Must be unique for the shop.
            maxLength: 32
            example: '30338272'
            default: null
          type:
            type: string
            description: The shop type.
            example: BoxC
            readOnly: true
        required:
        - id
      signature_confirmation:
        type: boolean
        description: Request signature confirmation from the recipient upon delivery. Not available for all services or routes. An additional fee may apply.
        default: false
        example: false
      status:
        type: string
        description: The order's current status. You may place an order in Holding to prevent fulfillment or Processing to fulfill the order.
        enum:
        - Holding
        - Processing
        example: Processing
      terms:
        description: The [Incoterms](https://en.wikipedia.org/wiki/Incoterms) for this shipment that affects which routes are available. If terms is not provided then the system will pick DDU or DDP if DDU is not available. DDP shipments will include tax and duty.
        type: string
        enum:
        - DAP
        - DDU
        - DDP
        default: DDU
        example: DDU
      to:
        $ref: '#/definitions/To'
      warehouse:
        type: object
        writeOnly: true
        description: Declare the warehouse where you want this order fulfilled. It will not be fulfilled until sufficient quantity exists at the specified warehouse. View the [Warehouses resource](/#tag/Warehouses) for a list.
        properties:
          id:
            type: string
            description: The warehouse ID.
            default: null
            example: WH0SZ001
        required:
        - id
      wholesale:
        type: boolean
        description: Indicates this order is wholesale.
        default: false
        example: true
    required:
    - shop
    - line_items
    - service
    - consignor
    - to
  ServiceUnavailable:
    $ref: '#/definitions/service-unavailable'
  Forbidden:
    $ref: '#/definitions/forbidden'
  Unauthorized:
    $ref: '#/definitions/unauthorized'
  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'
  fulfillment:
    type: object
    properties:
      created:
        description: The datetime this fulfillment was initiated.
        type: string
        example: '2024-06-17 15:43:03'
      fulfilled:
        description: The datetime this fulfillment was finalized.
        type: string
        example: '2024-06-27 08:33:49'
      fulfillment_fee:
        description: The fee for fulfilling this item or order.
        type: decimal
        example: 1.5
      id:
        description: The unique ID for this fulfillment.
        type: integer
        example: 4923
      packed:
        description: The datetime this fulfillment was packed.
        type: string
        example: '2024-06-18 11:09:24'
      packaging_fee:
        description: The fee for packaging the fulfillment.
        type: decimal
        example: 0.1
      packaging_slip_fee:
        description: The fee for printing and including a packing slip.
        type: decimal
        example: 0.25
      service:
        description: The shipping provider and/or service for this fulfillment.
        type: string
        example: BoxC Parcel
      shipment_id:
        description: The shipment ID if fulfilled by BoxC.
        type: integer
        example: 123456
      shipping_cost:
        description: The cost of shipping this fulfillment using a third party.
        type: decimal
        example: 0
      tracking_number:
        description: The tracking number for this fulfillment.
        type: string
        default: null
        example: '926149997649150002357'
      tracking_url:
        description: The tracking URL for this fulfillment if available.
        type: string
        format: uri
        example: https://track.boxc.com/?id=9261499976491500023573
  InternalServerError:
    $ref: '#/definitions/internal-server-error'
  unauthorized:
    description: Unauthorized
    content:
      application/json:
        schema:
          type: object
          summary: Unauthorized
          description: Lack of valid authentication credentials for the resource
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          accessToken:
            summary: Invalid access token
            description: Invalid access token
            value:
              code: 1005
              message: Invalid access token
              errors:
              - Invalid access token
  service-unavailable:
    type: object
    summary: Service Unavailable
    description: The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.
    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
  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
  from:
    description: This will appear as the return address on labels. A default return address will be used if one isn't provided in the request. The country code must match ```to.country```.
    type: object
    title: ReturnAddress
    properties:
      name:
        description: Can be a sender's name or company name.
        type: string
        maxLength: 40
        example: My Company Name
      street1:
        description: The sender's street address
        type: string
        maxLength: 50
        example: 113 INTL BROADWAY
      street2:
        description: Additional space for the sender's street address.
        type: string
        maxLength: 50
        default: null
        example: ''
      city:
        description: The sender's city.
        type: string
        maxLength: 40
        example: LOS ANGELES
      province:
        description: The sender's province or state. Conditional.
        type: string
        maxLength: 40
        example: CA
        default: null
      postal_code:
        description: The sender's postal code. Conditional.
        type: string
        maxLength: 10
        example: '91013'
        default: null
      country:
        description: The senders'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
  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
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