swagger: '2.0'
info:
  title: ChannelShipper & Royal Mail Public Labels Returns API
  description: Import your orders, retrieve your orders and generate labels.
  version: 1.0.0
basePath: /api/v1
consumes:
- application/json
produces:
- application/json
tags:
- name: Returns
  description: Reserved for OBA customers only.
paths:
  /returns/services:
    get:
      tags:
      - Returns
      summary: List available return services
      description: Returns a list of return services that can be used when creating return shipments.
      security:
      - Bearer: []
      responses:
        '200':
          description: Lists all available return services for generating return labels
          schema:
            $ref: '#/definitions/GetServicesResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /returns:
    post:
      tags:
      - Returns
      summary: Create a return shipment
      description: Creates a return label and returns shipment details including tracking number, QR code, and label.
      security:
      - Bearer: []
      parameters:
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/CreateReturnRequest'
        description: Return creation request
      responses:
        '200':
          description: Successfully created return shipment
          schema:
            $ref: '#/definitions/CreateReturnResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
definitions:
  ServiceCode:
    type: object
    properties:
      serviceCode:
        type: string
      serviceRegisterCode:
        type: string
  CustomerReference:
    type: object
    properties:
      reference:
        type: string
  Shipment:
    type: object
    properties:
      shippingAddress:
        $ref: '#/definitions/Address'
      returnAddress:
        $ref: '#/definitions/Address'
      customerReference:
        $ref: '#/definitions/CustomerReference'
  CreateReturnResponse:
    type: object
    properties:
      shipment:
        type: object
        properties:
          trackingNumber:
            type: string
          uniqueItemId:
            type: string
      qrCode:
        type: string
      label:
        type: string
  Address:
    type: object
    properties:
      title:
        type: string
      firstName:
        type: string
      lastName:
        type: string
      companyName:
        type: string
      addressLine1:
        type: string
      addressLine2:
        type: string
      addressLine3:
        type: string
      city:
        type: string
      county:
        type: string
      postcode:
        type: string
      country:
        type: string
      countryIsoCode:
        type: string
  CreateReturnRequest:
    type: object
    properties:
      service:
        $ref: '#/definitions/ServiceCode'
      shipment:
        $ref: '#/definitions/Shipment'
  ServiceItem:
    type: object
    properties:
      carrierGuid:
        type: string
        format: uuid
      carrierServiceGuid:
        type: string
        format: uuid
      serviceName:
        type: string
      serviceCode:
        type: string
  GetServicesResponse:
    type: object
    properties:
      services:
        type: array
        items:
          $ref: '#/definitions/ServiceItem'
securityDefinitions:
  Bearer:
    type: apiKey
    description: Authorization header using the Bearer scheme. Enter 'Bearer [space] and then your token.
    name: Authorization
    in: header