> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlast.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a returns shipment

> Create a shipment

Shipments are composed of a delivery and optionally a collection.


## OpenAPI

````yaml post /shipments/returns
openapi: 3.0.0
info:
  title: At Last Public Api Service
  description: This is the At Last public api specification.
  version: v1
servers:
  - url: https://api.atlast.co/v1
    description: Production
    variables: {}
security: []
tags: []
paths:
  /shipments/returns:
    post:
      description: Create a shipment
      operationId: Shipments_createReturnsShipment
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnShipmentRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnShipment'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
        '403':
          description: Access is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
      security:
        - OAuth2Auth: []
components:
  schemas:
    CreateReturnShipmentRequest:
      type: object
      required:
        - id
        - carrier
        - shipment
      properties:
        id:
          type: string
        carrier:
          allOf:
            - $ref: '#/components/schemas/ShipmentCarrierDetails'
          description: Carrier details
        shipment:
          allOf:
            - $ref: '#/components/schemas/CreateReturnShipmentDetails'
          description: Return Shipment details
        sendEmail:
          type: boolean
          description: >-
            Send customer email communications flag. Setting this to true will
            make At Last send any return related emails to the end user. This
            only impact return creation emails when using the API. This flag
            defaults to false.
          default: false
        ignore:
          type: array
          items:
            $ref: '#/components/schemas/IgnoreConstraint'
      description: Create return shipment request
    ReturnShipment:
      type: object
      required:
        - id
        - carrier
        - parcel
        - from
        - to
        - state
        - metadata
        - createdAt
        - hasDelivery
        - hasCollection
      properties:
        id:
          type: string
          format: uuid
          description: At last shipment id
        reference:
          type: string
          minLength: 1
          maxLength: 20
          description: Shipment Reference.
        reference2:
          type: string
          minLength: 1
          maxLength: 20
          description: Optional shipping reference (might not be suported by all carriers)
        carrier:
          $ref: '#/components/schemas/ShipmentCarrierDetails'
        parcel:
          $ref: '#/components/schemas/ShipmentParcel'
        from:
          $ref: '#/components/schemas/ShippingDetails'
        to:
          $ref: '#/components/schemas/ShippingDetails'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelData'
        trackingNumber:
          type: string
        trackingUrl:
          type: string
          format: uri
        statusDescription:
          type: string
        failureReason:
          type: string
        latestDeliveryEvent:
          $ref: '#/components/schemas/ShippingEvents'
        state:
          $ref: '#/components/schemas/ShippingStatus'
        deliveryState:
          $ref: '#/components/schemas/ShippingStatus'
        metadata:
          $ref: '#/components/schemas/ReturnShipmentMetadata'
        collectionRequestedTimeSlot:
          $ref: '#/components/schemas/CollectionTimeSlot'
        collection:
          $ref: '#/components/schemas/ShipmentCollectionData'
        createdAt:
          type: string
          format: date-time
        hasDelivery:
          type: boolean
        hasCollection:
          type: boolean
      description: Return Shipment resource
    GatewayErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        details:
          type: object
          additionalProperties: {}
    ShipmentCarrierDetails:
      type: object
      required:
        - id
        - serviceId
      properties:
        id:
          type: string
          format: uuid
        serviceId:
          type: string
    CreateReturnShipmentDetails:
      type: object
      required:
        - from
        - return
      properties:
        reference:
          type: string
          maxLength: 20
          description: |-
            Shipment Reference.
            **Max Length: 20**
        reference2:
          type: string
          maxLength: 20
          description: |-
            Optional shipping reference (might not be suported by all carriers)
            **Max Length: 20**
        from:
          allOf:
            - $ref: '#/components/schemas/ShippingDetails'
          description: Address information for the person that will be sending the shipment
        return:
          allOf:
            - $ref: '#/components/schemas/CreateReturnShipmentParcel'
          description: Return specific details
      description: Create return shipment request
    IgnoreConstraint:
      type: string
      enum:
        - SIZE
      description: >-
        Carrier constraints to ignore when creating a shipment. If not
        specified, all constraints will be checked.

        While our service constraints are based on carrier specifications, like
        size, these specifications are often vague and difficult to enforce.

        To allow for this, we provide a way to ignore specific constraints when
        creating a shipment.

        ** Note that this is not a replacement for the service constraints, it
        is only a way to ignore specific constraints when creating a shipment.
        And the API consumer is still responsible for ensuring that the shipment
        is valid. **
    ShipmentParcel:
      type: object
      required:
        - dimensions
        - weight
        - items
      properties:
        dimensions:
          $ref: '#/components/schemas/ParcelDimensions'
        weight:
          $ref: '#/components/schemas/Weight'
        items:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
              quantity:
                type: integer
                minimum: 1
              value:
                $ref: '#/components/schemas/Price'
              weight:
                $ref: '#/components/schemas/Weight'
            required:
              - quantity
          minItems: 1
    ShippingDetails:
      type: object
      required:
        - name
        - email
        - address
      properties:
        name:
          type: string
          description: |-
            The last name of the person sending or receiving the parcel.
            This is the minimum we need to create a shipment/collection.
        email:
          type: string
          format: email
          description: >-
            The email of the person sending or receiving the parcel.

            This is used for communication any communication with the user.

            This might be sent to carriers as well for them to manage their own
            communication with the user (notably for home collection updates)
        phoneNumber:
          type: string
          description: >-
            The phone number of the person sending or receiving the parcel.

            This can be sent to carriers for them to manage their own
            communication with the user.
        address:
          allOf:
            - $ref: '#/components/schemas/ShippingAddress'
          description: The shipping address detail
      description: >-
        Data used to specify address and receiver/sender details to create a
        shipment and collection.

        The data send in these address details are NOT verified. It's the
        responsibility of the caller to ensure the address data is correct or
        shipment/collection requests can fail.
    LabelData:
      type: object
      required:
        - url
        - type
      properties:
        url:
          type: string
          format: uri
        type:
          $ref: '#/components/schemas/LabelType'
    ShippingEvents:
      type: string
      enum:
        - BOOKED
        - COLLECTED
        - AT_HUB
        - IN_TRANSIT
        - OUT_FOR_DELIVERY
        - FAILED_ATTEMPT
        - DELIVERED
        - ON_HOLD
        - ADDRESS_ISSUE
        - RETURNED_TO_SENDER
        - TRACKING_EXPIRED
        - CANCELLED
        - AWAITING_CUSTOMER_COLLECTION
        - PACKING
        - MISSING
        - DAMAGED
    ShippingStatus:
      type: string
      enum:
        - AWAITING_BOOKING
        - READY
        - ONGOING
        - COMPLETE
        - CANCELED
        - FAIL
    ReturnShipmentMetadata:
      type: object
      required:
        - returnId
        - merchant
        - user
        - items
      properties:
        returnId:
          type: string
          format: uuid
        externalId:
          type: string
        merchant:
          type: object
          properties:
            id:
              type: string
          required:
            - id
        user:
          type: object
          properties:
            email:
              type: string
              format: email
          required:
            - email
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReturnItemDetails'
          minItems: 1
    CollectionTimeSlot:
      type: object
      required:
        - date
      properties:
        date:
          type: string
          description: The time slot date, in the format YYYY-MM-DD.
        time:
          type: string
          description: >-
            An optional time string, can be exact or a time range, will be
            carrier dependent.
      description: Resovled collection time slot
    ShipmentCollectionData:
      type: object
      required:
        - bookedTimeSlot
        - rebooked
      properties:
        bookedTimeSlot:
          $ref: '#/components/schemas/CollectionTimeSlot'
        rebooked:
          type: boolean
    CreateReturnShipmentParcel:
      type: object
      required:
        - dimensions
        - orderIdentifier
        - items
      properties:
        dimensions:
          $ref: '#/components/schemas/ParcelDimensions'
        orderIdentifier:
          type: string
          minLength: 1
        items:
          type: array
          items:
            type: object
            properties:
              quantity:
                type: integer
                minimum: 1
              value:
                $ref: '#/components/schemas/Price'
              weight:
                $ref: '#/components/schemas/Weight'
              reason:
                $ref: '#/components/schemas/ReturnReasons'
            required:
              - quantity
              - value
              - weight
              - reason
          minItems: 1
    ParcelDimensions:
      type: object
      required:
        - width
        - height
        - length
        - unit
      properties:
        width:
          type: number
          description: >-
            Expected length of the shipment package in the unit of measure
            specified in the unit field
          minimum: 0
          exclusiveMinimum: true
        height:
          type: number
          description: >-
            Expected height of the shipment package in the unit of measure
            specified in the unit field
          minimum: 0
          exclusiveMinimum: true
        length:
          type: number
          description: >-
            Expected length of the shipment package in the unit of measure
            specified in the unit field
          minimum: 0
          exclusiveMinimum: true
        unit:
          allOf:
            - $ref: '#/components/schemas/SizeUnit'
          description: The unit of measure used for all the dimension values in the parcel
      description: >-
        The details for the parcel that you wish to create. Dimensions and
        items, together with their weights, need to be specified in order for us
        to create a shipment
    Weight:
      type: object
      required:
        - value
        - unit
      properties:
        value:
          type: number
          description: |-
            Specifies the value of the weight, weights values can be floats.
            **Min Value: 0 non inclusive**
          minimum: 0
          exclusiveMinimum: true
        unit:
          allOf:
            - $ref: '#/components/schemas/WeightUnits'
          description: The unit of the value as seen in WeightUnits enum.
      description: Weight model used to define weights
    Price:
      type: object
      required:
        - value
        - currency
      properties:
        value:
          type: number
          minimum: 0
          description: |-
            Specifies the value price instance, price values can be floats.
            **Min Value: 0**
        currency:
          type: string
          description: ISO 4217 currency codes
      description: Price model used to define any currency exchange or value.
    ShippingAddress:
      type: object
      required:
        - line1
        - city
        - postCode
      properties:
        line1:
          type: string
          maxLength: 40
          description: Line 1 of the address.
        line2:
          type: string
          maxLength: 40
          description: Line 2 of the address (optional).
        line3:
          type: string
          maxLength: 40
          description: Line 3 of the address (optional).
        city:
          type: string
          description: Address city.
        postCode:
          type: string
          minLength: 4
          description: Address postcode. Needs to be a valid UK postcode.
      description: >-
        Data used to specify address and receiver/sender details to create a
        shipment.

        The data send in these address details are NOT verified. It's the
        responsibility of the caller to ensure the address data is correct or
        shipment/collection requests can fail.
    LabelType:
      type: string
      enum:
        - PAPERLESS
        - PAPER
    ReturnItemDetails:
      type: object
      required:
        - itemId
        - reason
        - quantity
      properties:
        itemId:
          type: string
        reason:
          $ref: '#/components/schemas/ReturnReasons'
        quantity:
          type: integer
          minimum: 1
    ReturnReasons:
      type: string
      enum:
        - TOO_LARGE
        - TOO_SMALL
        - DIFFERENT_IMAGE
        - DIFFERENT_DESCRIPTION
        - POOR_QUALITY
        - TOO_EXPENSIVE
        - CHANGED_MIND
        - ARRIVED_LATE
        - ACCIDENTAL_PURCHASE
        - DAMAGED
        - INCORRECT_ITEM
        - OTHER
        - RECYCLE
        - REPAIR_OR_REPLACEMENT
      description: Supported returns reasons
    SizeUnit:
      type: string
      enum:
        - CM
      description: Supported size units
    WeightUnits:
      type: string
      enum:
        - GRAMS
        - KILOGRAMS
        - OUNCES
        - POUNDS
      description: Supported weight units
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.atlast.co/oauth2/token
          scopes: {}

````