---
swagger: "2.0"
info:
  description: Shipwire's Containers API
  version: "3.0"
  title: Shipwire Containers API
host: api.shipwire.com
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- basicAuth: []
paths:
  /api/v3.1/containers:
    get:
      summary: Get containers
      description: Get a collection of containers.
      operationId: getApiV31Containers
      produces:
      - application/json
      parameters:
      - name: isActive
        in: query
        description: Returns containers that are active or not. Valid options are 1 or 0.
        required: false
        type: integer
        format: enum
        enum:
        - 1
        - 0
      - name: warehouseIds
        in: query
        description: Returns all containers that exist in the provided warehouse. Single warehouse's id or comma separated list of warehouse ids.
        required: false
        type: string
      - name: warehouseExternalIds
        in: query
        description: Returns all containers that exist in the provided warehouse. Single warehouse's external id or comma separated list of warehouse external ids.
        required: false
        type: string
      - name: type
        in: query
        description: Container type. Valid options are 'box', 'envelope', 'tube', 'pallet'
        required: false
        type: array
        items:
          type: string
          format: enum
          enum:
          - box
          - envelope
          - tube
          - pallet
        collectionFormat: multi
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/GetContainersResponse'
    post:
      summary: Create a new container
      description: ""
      operationId: postApiV31Containers
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: ""
        required: true
        schema:
          $ref: '#/definitions/CreateANewContainerRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/CreateANewContainerResponse'
  /api/v3.1/containers/{id}:
    get:
      summary: Get a container
      description: Get a container by container's id or external id.
      operationId: getApiV31ContainersById
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: The container's id or external id.
        required: true
        type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/getAContainerResponse'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/404ContainerNotFoundResponse'
    put:
      summary: Update a container
      description: Modify a container based on its containers's id or external id
      operationId: putApiV31ContainersById
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: The containers's id or external id.
        required: true
        type: string
      - in: body
        name: body
        description: ""
        required: true
        schema:
          $ref: '#/definitions/UpdateAContainerRequest'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/UpdateAContainerResponse'
securityDefinitions:
  basicAuth:
    type: basic
definitions:
  GetContainersResponse:
    title: Get containers response
    allOf:
    - $ref: '#/definitions/GetResponseModel'
    - {}
    description: Get container details
  CreateANewContainerRequest:
    type: object
    required:
    - basis
    - dimensions
    - isActive
    - name
    - type
    - values
    - warehouseId
    properties:
      warehouseExternalId:
        type: string
        example: WH005
        description: A unique user-provided identifier for a Shipwire Anywhere warehouse in an external system.
      externalId:
        type: string
        example: "1002"
        description: A unique user-provided identifier for a container in an external system.
      name:
        type: string
        example: 25.00 X 5.00 X 5.00 box update
        description: A unique identifier for the container in the Shipwire system. It can be standardized to be the dimensions of the container (length, width, height) and type.
      type:
        type: string
        format: enum
        example: box
        description: This is the type of container based on the contents stored in it.
        enum:
        - box
        - envelope
        - tube
        - pallet
      isActive:
        type: integer
        format: enum
        example: 1
        description: A boolean which indicates whether or not the warehouse can use the container for a particular customer for packaging
      warehouseId:
        type: integer
        example: 3071
        description: A unique identifier for a Shipwire or Shipwire Anywhere warehouse. (See the warehouses API.)
      basis:
        type: string
        example: "5045.0"
        description: Basis is a parameter used to prioritize the use of some containers over others. To give preference to one container over another, assign a higher basis value.
      serviceSpecificCarrierCode:
        type: string
        example: FDX FT
        description: It indicates that this container is used with a particular carrier service (eg. FDX 1D).
      dimensions: {}
      values: {}
    title: Create a new container request
    description: Request to create new container
  404ContainerNotFoundResponse:
    title: Create a new container response
    allOf:
    - $ref: '#/definitions/404GetResponseModel'
    - {}
    description: Get using invalid container Id
  CreateANewContainerResponse:
    title: Create a new container response
    allOf:
    - $ref: '#/definitions/PutPostResponseModel'
    - {}
    description: Response post container creation
  UpdateAContainerRequest:
    type: object
    required:
    - basis
    - dimensions
    - isActive
    - name
    - type
    - values
    - warehouseId
    properties:
      warehouseExternalId:
        type: string
        example: WH005
        description: A unique user-provided identifier for a Shipwire Anywhere warehouse in an external system.
      externalId:
        type: string
        example: "1002"
        description: A unique user-provided identifier for a container in an external system.
      name:
        type: string
        example: 25.00 X 5.00 X 5.00 box update
        description: A unique identifier for the container in the Shipwire system. It can be standardized to be the dimensions of the container (length, width, height) and type.
      type:
        type: string
        format: enum
        example: box
        description: This is the type of container based on the contents stored in it.
        enum:
        - box
        - envelope
        - tube
        - pallet
      isActive:
        type: integer
        format: enum
        example: 1
        description: A boolean which indicates whether or not the warehouse can use the container for a particular customer for packaging
      warehouseId:
        type: integer
        example: 3071
        description: A unique identifier for a Shipwire or Shipwire Anywhere warehouse. (See the warehouses API.)
      basis:
        type: string
        example: "5045.0"
        description: Basis is a parameter used to prioritize the use of some containers over others. To give preference to one container over another, assign a higher basis value.
      serviceSpecificCarrierCode:
        type: string
        example: FDX FT
        description: It indicates that this container is used with a particular carrier service (eg. FDX 1D).
      dimensions: {}
      values: {}
    title: Update a container request
    description: Request to update container information
  UpdateAContainerResponse:
    title: Update a container response
    allOf:
    - $ref: '#/definitions/PutPostResponseModel'
    - {}
    description: Response for container update
  getAContainerResponse:
    type: object
    properties:
      status:
        type: integer
        example: 200
        description: This is the HTTP status code.
      message:
        type: string
        example: Successful
        description: This is the HTTP status message.
      resourceLocation:
        type: string
        example: https://api.shipwire.com/api/v3.1/containers/245641
        description: A URL that gives more information about the linked resource. A 'null' value would mean that no further information is available for that resource.
      resource:
        $ref: '#/definitions/ContainerResponseModel'
    title: Get a Container Response
    description: Get container details
  ContainerDimensions:
    type: object
    properties:
      length:
        type: number
        example: 20.0
        description: This is the length of the container based on its Unit of Measurement (lengthUnit)
        minimum: 0.1
        maximum: 108
      width:
        type: number
        example: 5.0
        description: This is the width of the container based on its Unit of Measurement (widthUnit)
        minimum: 0.1
        maximum: 108
      height:
        type: number
        format: float
        example: 5.0
        description: This is the height of the container based on its Unit of Measurement (heightUnit)
        minimum: 0.1
        maximum: 108
      weight:
        type: number
        format: float
        example: 0.46
        description: This is the weight of the container based on its Unit of Measurement (weightUnit)
      maxWeight:
        type: number
        format: float
        example: 40.0
        description: This is the maximum weight that the container can hold based on its Unit of Measurement (maxWeightUnit)
      lengthUnit:
        type: string
        example: IN
        description: This is the Unit of Measurement for Container length (e.g. inches)
      widthUnit:
        type: string
        example: IN
        description: This is the Unit of Measurement for Container width (e.g. inches)
      heightUnit:
        type: string
        example: IN
        description: This is the Unit of Measurement for Container height (e.g. inches)
      weightUnit:
        type: string
        example: LB
        description: This is the Unit of Measurement for Container weight (e.g. pounds)
      maxWeightUnit:
        type: string
        example: LB
        description: This is the Unit of Measurement for Container's max weight (e.g. pounds)
  ContainerValue:
    type: object
    properties:
      costValue:
        type: number
        example: 20.0
        description: This is the cost value for the container. During the carton selection phase for an order, Shipwire will first consider containers with a lower cost, even if chosing one will end up making the shipping cost comparatively higher. (i.e. Shipwire will chose a container 1 with a $0 cost over a container 2 with a $1 cost, even if the shipping cost for using container 1 is higher than it would be using container 2.)
        minimum: 0.0
        maximum: 1000000
      retailValue:
        type: number
        example: 20.0
        description: This is the retail value for the container. Container retail value will be added to the shipping quote for the customer. If a merchant doesn't plan to charge customers for cartons/boxes, the container retail value should be set to $0.
        minimum: 0.0
        maximum: 1000000
      costValueCurrency:
        type: string
        example: USD
        description: This is the currency used in determining cost value for the container.
      retailValueCurrency:
        type: string
        example: USD
        description: This is the currency used in determining retail value for the container.
  404GetResponseModel:
    type: object
    properties:
      status:
        type: integer
        example: 404
        description: This is the HTTP status code.
      message:
        type: string
        example: Container not found
        description: This is the HTTP status message.
      resourceLocation:
        type: string
        example: null
        description: A URL that gives more information about the linked resource. A null value would mean that no further information is available for that resource.
  PutPostResponseModel:
    type: object
    properties:
      status:
        type: integer
        example: 200
        description: This is the HTTP status code.
      message:
        type: string
        example: Successful
        description: This is the HTTP status message.
      warnings:
        type: object
        description: A notification that warns the user of something or that serves as a caution. Eg. an externalId supplied greater than 32 characters.
        properties: {}
      errors:
        type: object
        description: A fatal error that prevents the user from performing some action. (e.g. invalid warehouseId specified when creating a container)
        properties: {}
      resourceLocation:
        type: string
        example: https://api.shipwire.com/api/v3.1/containers?offset=0&limit=20
        description: A URL that gives more information about the linked resource. A null value would mean that no further information is available for that resource.
  GetResponseModel:
    type: object
    properties:
      status:
        type: integer
        example: 200
        description: This is the HTTP status code.
      message:
        type: string
        example: Successful
        description: This is the HTTP status message.
      resourceLocation:
        type: string
        example: https://api.shipwire.com/api/v3.1/containers?offset=0&limit=20
        description: A URL that gives more information about the linked resource. A null value would mean that no further information is available for that resource.
  ContainerResponseModel:
    type: object
    properties:
      id:
        type: integer
        example: 245641
        description: A unique auto-generated ID assigned to each new container added to the Shipwire Platform.
      externalId:
        type: string
        example: "1002"
        description: A unique user-provided identifier for a container in an external system.
      name:
        type: string
        example: 25.00 X 5.00 X 5.00 box update
        description: A unique identifier for the container in the Shipwire system. It can be standardized to be the dimensions of the container (length, width, height) and type.
      type:
        type: string
        format: enum
        example: box
        description: This is the type of container based on the contents stored in it.
        enum:
        - box
        - envelope
        - tube
        - pallet
      isActive:
        type: integer
        format: enum
        example: 1
        description: A boolean which indicates whether or not the warehouse can use the container for a particular customer for packaging
      warehouseId:
        type: integer
        example: 3071
        description: A unique identifier for a Shipwire or Shipwire Anywhere warehouse. (See the warehouses API.)
      warehouseExternalId:
        type: string
        example: WH005
        description: A unique user-provided identifier for a Shipwire Anywhere warehouse in an external system.
      basis:
        type: string
        example: "5045.0"
        description: Basis is a parameter used to prioritize the use of some containers over others. To give preference to one container over another, assign a higher basis value.
      serviceSpecificCarrierCode:
        type: string
        example: FDX FT
        description: It indicates that this container is used with a particular carrier service (eg. FDX 1D).
      dimensions:
        $ref: '#/definitions/ContainerResponseModel_dimensions'
      values:
        $ref: '#/definitions/ContainerResponseModel_values'
  ContainerResponseModel_dimensions:
    properties:
      resourceLocation:
        type: string
        example: null
      resource:
        $ref: '#/definitions/ContainerDimensions'
  ContainerResponseModel_values:
    properties:
      resourceLocation:
        type: string
        example: null
      resource:
        $ref: '#/definitions/ContainerValue'
