openapi: 3.1.0
info:
  title: Create headless return
  description: >
    <div class="notices warning"><img src="/images/warning.svg?featherlight=false" /><p>This is only for headless merchants. Please see the <a href="/guides/headless-returns/" target="_blank">implementation guide</a>
    for more details.</p></div>
    
    
    ## Overview
    
    For partners and merchants who want to keep their own return flow, but use Happy Returns to manage return shipments across various drop-off methods. 
    View the <a href="/guides/headless-returns/" target="_blank">implementation guide</a> for more details.
    
    
    ## Authentication
    
    Partners can authenticate for this endpoint by following the steps here: <a href="../#authentication"
    target="_blank">API set up</a>.
servers:
  -
    url: 'https://partner.happyreturns.com'
    description: ''
paths:
  /create_return:
    summary: Create Headless Return
    description: >
      This endpoint will take a JSON body defined below and create a return. The RMA ID and URL to
      download the QR code will be provided in the response.
      
      
      The `display` values should include the primary attributes of the product, these will be displayed
      to the user and Returnista to recognize the product.
      
      
      Any information provided to this endpoint will also be provided in the Return Webhook if
      configured.
      
      
      Returns that contain too many items are not eligible for Return Bar drop off and the API will
      respond with an error message.  By default returns with 10 or more items are not eligible for
      Return Bar returns.
    post:
      requestBody:
        description: Request body to send to create a return
        content:
          application/json:
            schema:
              oneOf:
                -
                  $ref: '#/components/schemas/CreateReturnRequestRetailerStoreAndReturnBar'
                -
                  $ref: '#/components/schemas/CreateReturnRequestMailMailNoLabelAndMailNoBoxNoLabel'
        required: true
      parameters:
        -
          name: X-Hr-Apikey
          description: >-
            A partner’s API key. The partner must be authorized by Happy Returns to create
            headless returns. Contact Happy Returns to grant permission.
            
            <br /> <br /> Example: `your-api-key`
          schema:
            type: string
          in: header
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                oneOf:
                -
                  $ref: '#/components/schemas/CreateReturnResponseForReturnBarAndRetailerStore'
                -
                  $ref: '#/components/schemas/CreateReturnResponseForMailAndMailNoLabel'
                -
                  $ref: '#/components/schemas/CreateReturnResponseForMailNoBoxNoLabel'

          description: Return was successfully created
        '400':
          content:
            application/json:
              schema:
                oneOf:
                  -
                    $ref: '#/components/schemas/TooManyItemsInReturn'
                  -
                    $ref: '#/components/schemas/DropoffNotSupported'
                  - 
                    $ref: '#/components/schemas/DropoffMehtodNotOfferedByRetailer'
                  - 
                    $ref: '#/components/schemas/NoShippingOptionsProvided'
                  - 
                    $ref: '#/components/schemas/NoAddressProvided'
          description: Error message sent when too many items were provided in the request or dropoff method is not supported by the retailer
        '401':
          content:
            application/json:
              schema:
                oneOf:
                  -
                    $ref: '#/components/schemas/InvalidAPIKey'
                  -
                    $ref: '#/components/schemas/NoPermissionToCreateQRCode'
          description: >-
            Error message sent when partner does not have permission or missing/invalid
            X-Hr-Apikey
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoDropoffMethodsAvailable'
          description: No drop off methods available for this return.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal server error
      summary: Create Return
      description: 'Creates a return for headless retailers. https://partner.happyreturns.com/create_return'
    parameters:
      -
        name: X-Hr-Apikey
        description: >-
          A partner’s API key. The partner must be authorized by Happy Returns to create new returns. Contact Happy Returns to grant permission.
          
          <br /> <br /> Example: `your-api-key`
        schema:
          type: string
        in: header
        required: true
components:
  schemas:
    Detail:
      title: Additional Details
      description: Additional details that can be provided about the purchase
      type: object
      properties:
        product_id:
          description: A product ID is a unique identifier for a product in the purchase.
          type: string
        serialNumber:
          description: A serial number is a unique identifier for the product in the purchase
          type: string
        weight:
          format: double
          description: >-
            Weight of the product without the unit (Must supply `weight_unit` along with it,
            otherwise it will be ignored)
          type: number
        weightUnit:
          description: >-
            Unit of the weight must be lb, oz, g, kg (Must supply `weight` along with it,
            otherwise it will be ignored)
          type: string
        brand:
          description: >-
            Brand information for the item.
          type: string
        additional_scannable_codes:
          description: >-
            A list of scannable identifiers, along with current upc, sku, and product ID parameters are used for item verification.
          type: array
          items:
            type: string
      example:
        product_id: Prod-123
        serialNumber: ABC123
        weight: 2.4
        weightUnit: lb
        brand: modern-retailer
        additional_scannable_codes: ["sku-123", "upc-456"]
    ShippingAddress:
      title: Shipping Address
      description: Shipping address
      type: object
      properties:
        address1:
          description: Shipping address line 1 for the customer
          type: string
        address2:
          description: Shipping address line 2 for the customer
          type: string
        city:
          description: Shipping city for the customer
          type: string
        country:
          description: Shipping country for the customer
          type: string
        latitude:
          description: Shipping latitude coordinate for the customer
          type: number
        longitude:
          description: Shipping longitude coordinate for the customer
          type: number
        province:
          description: Shipping province/state for the customer
          type: string
        country_code:
          description: Shipping country 2 letter ISO code for the customer
          type: string
        province_code:
          description: Shipping province/state code for the customer
          type: string
        zip_code:
          description: The Zip Code of the order’s shipping address
          type: string
      example:
        address1: 100 Willshire
        address2: ''
        city: Santa Monica
        country: United States
        latitude: 34.010929
        longitude: -118.491508
        province: California
        country_code: US
        province_code: CA
        zip_code: '90401'
    MailDestinationAddress:
      title: Mail Destination Address
      description: ''
      type: object
      properties:
        name:
          description: Name of the retailer's destination
          type: string
        phone:
          description: Phone number of the retailer's destination
          type: string
        address1:
          description: Destination address line 1 for the retailer
          type: string
        address2:
          description: Destination address line 2 for the retailer
          type: string
        city:
          description: Destination city for the retailer
          type: string
        country:
          description: Destination country for the retailer
          type: string
        province:
          description: Destination province/state for the retailer
          type: string
        country_code:
          description: Destination country 2 letter ISO code for the retailer
          type: string
        province_code:
          description: Destination province/state code for the retailer
          type: string
        zip_code:
          description: The Zip Code of the retailer's mail destination address
          type: string
      example:
        address1: 100 Willshire
        address2: ''
        city: Santa Monica
        country: United States
        province: California
        country_code: US
        province_code: CA
        zip_code: '90401'
    CustomReference:
      title: Mail label custom reference
      description: ''
      type: object
      properties:
        code:
          description: >-
            Code is dependent on the carrier. Code from the [UPS supported references](https://developer.ups.com/api/reference/shipping/appendix2?loc=en_US#tabs_1_tabPane_4).
            For example: AJ, AT, BM 9V, ON, DP, 3Q, IK, MK, MJ, PM, PC, PO, RQ, RZ, SA, SE, ST, TN. If code is omitted or not recognized by the carrier, it is not submitted.
          type: string
        value:
          description: Reference value. Cannot be empty.
          type: string
        barcode_indicator:
          description: Indicates whether the reference is shown as a barcode or not. Defaults to false if not provided.
          type: boolean
      example:
        address1: 100 Willshire
        address2: ''
        city: Santa Monica
        country: United States
        province: California
        country_code: US
        province_code: CA
        zip_code: '90401'
    CreateReturnResponseForReturnBarAndRetailerStore:
      title: Return Bar and Retailer Store
      description: Response returned after creating a return for Return Bar or Retailer Store
      required:
        - rma_id
        - qr_code
      type: object
      properties:
        rma_id:
          description: >-
            The shopper facing RMA ID for the return that was created. This ID can be used by the
            customer to look up a return at a return bar that was started through the
            partner/retailer return app by providing it to the Returnista
          type: string
        qr_code:
          description: >-
            The URL to download the QR code generated for the return. This QR code can be used by
            the customer to more quickly look up a return at a return bar that was started through
            the partner/retailer return app by showing it to the Returnista to scan
          type: string
      example:
        rma_id: HRXLIR78
        qr_code: 'https://zdemo.happyreturns.com/getqrcode?code=HRXLIR78'

    CreateReturnResponseForMailNoBoxNoLabel:
      title: Mail No Box No Label
      description: Response returned after creating a return for Mail No Box No Label
      required:
        - rma_id
        - qr_code
      type: object
      properties:
        rma_id:
          description: >-
            The shopper facing RMA ID for the return that was created. This ID can be used by the
            customer to look up a return at a return bar that was started through the
            partner/retailer return app by providing it to the Returnista
          type: string
        qr_code:
          description: >-
            The URL to download the QR code generated for the return. This QR code can be used by
            the customer to more quickly look up a return at a return bar that was started through
            the partner/retailer return app by showing it to the Returnista to scan
          type: string
        items:
          description: >-
            The items that are being returned, with the order number, order line item ID, and Happy Returns item ID.
          type: array
          items:
            type: object
            $ref: '#/components/schemas/MailNoLabelItemsResponse'
      example:
        rma_id: HRXLIR78
        qr_code: 'https://zdemo.happyreturns.com/getqrcode?code=HRXLIR78'
        items:
          order_number: '342263'
          order_line_item_id: '13676457984066-1-8-0'
          happy_returns_item_id: '9f22ce7c-ea9d-45a4-94e0-5d536ecace10'
          upc: 'SKDFHWEW-DKFD'
          sku: 'nomshrts-1'
    CreateReturnResponseForMailAndMailNoLabel:
      title: By Mail and Mail No Label
      description: Response returned after creating a return for Mail or Mail No Label
      required:
        - rma_id
        - qr_code
      type: object
      properties:
        rma_id:
          description: >-
            The shopper facing RMA ID for the return that was created. This ID can be used by the
            customer to look up a return at a return bar that was started through the
            partner/retailer return app by providing it to the Returnista.
          type: string
        label_url:
          description: >-
            The URL to download the QR code for pre-packaged label generated for the return.
          type: string
        tracking_number:
          description: >-
            The tracking number for the return that was created, related to the pre-packaged label. This tracking number can be used
            by the customer to track the return shipment.
          type: string
        items:
          description: >-
            The items that are being returned, with the order number, order line item ID, and Happy Returns item ID.            
          type: array
          items:
            type: object
            $ref: '#/components/schemas/MailNoLabelItemsResponse'
      example:
        rma_id: HRXLIR78
        label_url: 'https://zdemo.happyreturns.com/label?returnID=4988939e-c135-46f7-b2c4-2b250b543653'
        tracking_number: '1234567890'
        items: 
          order_number: '342263'
          order_line_item_id: '13676457984066-1-8-0'
          happy_returns_item_id: '9f22ce7c-ea9d-45a4-94e0-5d536ecace10'
          upc: 'SKDFHWEW-DKFD'
          sku: 'nomshrts-1'
    Instance:
      title: Return Item
      description: Return Item
      required:
        - id
        - images
        - name
        - order_number
        - reason
        - sku
        - when
        - zip_code
      type: object
      properties:
        id:
          description: >-
            Unique ID for the line item the purchase came from. Can also use the SKU - does not
            need to be unique in the return
          type: string
        order_number:
          description: Order number of the order the purchase belongs to.
          type: string
        external_rma_id:
          description: The unique identifier for the return generated by the retailer's or partner's internal systems.
          type: string
        name:
          description: Display name of the product.
          type: string
        sku:
          description: 'The SKU of the product, used for display and reporting.'
          type: string
        upc:
          description: |
            The UPC of the product, if available to use for display and reporting.
          type: string
        price:
          description: 'The price of the product with currency, invalid format will be ignored.'
          type: string
        images:
          description: Images used to identify the purchase being returned
          type: array
          items:
            type: string
        when:
          format: date-time
          description: >-
            The date when the order the purchase belongs to was placed. This date is used to
            determine whether the order is inside the return window (if the return window is
            managed by Happy Returns).
          type: string
        details:
          $ref: '#/components/schemas/Detail'
          description: Additional details that can be provided about the purchase
          properties:
            serialNumber:
              type: string
            weight:
              format: double
              type: number
            weightUnit:
              type: string
            brand:
              type: string
            additional_scannable_codes:
              type: array
              items:
                type: string
        display:
          description: >-
            The display values for the product, such as Color, Size, Material, Fitting, etc. that
            distinguishes this product from other products. This is displayed to identify the
            product being returned.
          type: array
          items:
            $ref: '#/components/schemas/Display'
        reason:
          description: The reason the customer is returning the purchase
          type: string
        reason_type:
          description: 'The reason type of the return; Can be one of “damaged”, “wrong-item” or ""'
          type: string
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
          description: Shipping Address
          properties:
            address1:
              type: string
            address2:
              type: string
            city:
              type: string
            country:
              type: string
            latitude:
              format: double
              type: number
            longitude:
              format: double
              type: number
            province:
              type: string
            country_code:
              type: string
            province_code:
              type: string
            zip_code:
              type: string
        zip_code:
          description: The Zip Code of the order’s shipping address
          type: string
        refund_methods_offered:
          description: >-
            Can be one or more from the following `refund`, `store credit`, `exchange - same price
            point` or `exchange - upsell`
            
            <ul>
            
            <li><code>refund</code> - shopper receives a refund to their original form of
            payment</li>
            
            <li><code>store credit</code> - shopper receives a refund in the form of store credit
            or e-gift card</li>
            
            <li><code>exchange - same price point</code> - shopper receives an even exchange for a
            similar item</li>
            
            <li><code>exchange - upsell</code> - shopper receives different price point exchange
            typically shopping for new/unrelated items</li>
            
            </ul>
          type: array
          items:
            type: string
        label:
          description: Allows customization of the Happy Returns Hub item label beyond the default available options. Hub item labels are not necessary for most headless implementations.
          type: object
          $ref: '#/components/schemas/Label'
      example:
        id: 12950087565378-3-1
        order_number: '290670'
        external_rma_id: RET2024XYZ999
        name: Nomadic Coast Short
        sku: nomshrts-1
        upc: SKDFHWEW-DKFD
        price: 50.00 USD
        images:
          - >-
            https://cdn.shopify.com/s/files/1/0552/3557/5874/products/olive_shorts.jpg?v=1661958339
        when: '2024-01-21T20:19:24Z'
        details:
          serialNumber: s243415236
          weight: 2.4
          weightUnit: lb
          brand: modern-retailer
          additional_scannable_codes:
            - sku-123
            - upc-456
        display:
          -
            label: Size
            value: '29'
          -
            label: Color
            value: Olive
        reason: damaged
        reason_type: damaged
        shipping_address:
          address1: 100 Willshire
          address2: ''
          city: Santa Monica
          country: United States
          latitude: 34.010929
          longitude: -118.491508
          province: California
          country_code: US
          province_code: CA
          zip_code: '90401'
        zip_code: '90401'
        refund_methods_offered:
          - refund
          - store credit
          - exchange - same price point
          - exchange - upsell
    MailNoLabelItemsResponse:
      title: Returning Items
      description: Return Items
      required:
        - order_number
        - order_line_item_id
        - happy_returns_item_id
      type: object
      properties:
        order_number:
          description: >-
            The unique identifier for the order as provided by the retailer.
          type: string
        order_line_item_id:
          description: >-
            Unique ID for the line item the purchase came from. Can also use the SKU - does not
            need to be unique in the return.
          type: string
        happy_returns_item_id:
          description: >-
            The unique identifier for the returned item.
          type: string
        upc:
          description: >-
            The UPC of the product, if available to use for display and reporting.
          type: string
        sku:
          description: >-
            The SKU of the product, used for display and reporting.
          type: string
      example:
        order_number: '342263'
        order_line_item_id: '13676457984066-1-8-0'
        happy_returns_item_id: '9f22ce7c-ea9d-45a4-94e0-5d536ecace10'
        upc: 'SKDFHWEW-DKFD'
        sku: 'nomshrts-1'
    TooManyItemsInReturn:
      description: Too many returning items are provided for a return bar return
      type: string
      example: Return contains more than 9 item(s) and is not eligible for Return Bar drop off.
    DropoffNotSupported:
      description: Dropoff method provided is not supported by the retailer
      type: string
      example: Retailer does not offer specified dropoff method return-bar for this return
    NoDropoffMethodsAvailable:
        description: When there are no drop off methods available for a return
        type: string
        example: no drop off methods available for this return
    DropoffMehtodNotOfferedByRetailer:
        description: >-
          When the retailer does not support the dropoff method specified on `dropoff_method_id` for the return.
          The example refers for `mail-nolabel`, but the error message will be specific to the dropoff method.
        type: string
        example: Retailer does not offer specified dropoff method mail-nolabel for this return.
    NoShippingOptionsProvided:
        description: >-
          Returned when there are no shipping options configured for the retailer and dropoff method.
        type: string
        example: Missing return shipment shipping options
    NoAddressProvided:
        description: >-
          Returned when there is no shipping address provided for the return (`returning[].shipping_address`).
        type: string
        example: No shipping address
    InvalidAPIKey:
      title: Invalid API key is sent or API key is missing
      description: Invalid API key is sent or API key is missing
      type: object
      properties:
        errorMessage:
          description: Error message
          type: string
        errorCode:
          description: Error code
          type: string
      example:
        errorMessage: 'invalid credentials: record not found'
        errorCode: '004'
    NoPermissionToCreateQRCode:
      title: No permission to create start return
      description: Error message sent when partner does not have permission to create QR code
      type: string
      example: Partner no-access-partner does not have permission to create QR codes
    Display:
      title: Display object
      description: Display object that distinguishes a product from other products
      required:
        - label
        - value
      type: object
      properties:
        label:
          description: 'The display label for the attribute, such as Color, Size, etc.'
          type: string
        value:
          description: |
            The display value for the attribute, such as Red, Green, Blue, 7, 8, 9.
          type: string
      example:
        label: Size
        value: '29'
    Label:
      title: Root Type for Label
      description: Allows customization of the Happy Returns Hub item label beyond the default available options. Hub item labels are not necessary for most headless implementations. Data to be placed onto a printed label for proper identification of the product
      type: object
      properties:
        note:
          description: Note for the label. Can be the product SKU unless another value is desired.
          type: string
        barcode:
          description: Barcode value for the label. Can be the product SKU unless another value is desired.
          type: string
        representation:
          description: |-
            Encoded barcode format.

            Can be one of:
            * qr
            * qr_q
            * datamatrix
            * codabar
            * code39
            * ean
            * code128
          type: string
      example:
        note: FLT-RSE-7.5
        barcode: FLT-RSE-7.5
        representation: code128
    CreateReturnRequestRetailerStoreAndReturnBar:
      title: Return Bar and Retailer Store
      description: Create Return for Return Bar or Retailer Store Request payload example
      required:
        - email
        - retailer_id
      type: object
      properties:
        retailer_id:
          description: >-
            The identifier of the retailer for the returning items. This needs to match an already
            existing retailer, cannot be arbitrary.
          type: string
        email:
          description: The email address on the order for sending email confirmations for the return
          type: string
        return_fee:
          description: Return fee amount with currency code
          type: string
        dropoff_method_id:
          description: >-
            Shopper selected dropoff method ID of the return, which can be one of the following `return-bar`, `in-store`, 
            `mail`, `mail-nolabel`, or `mail-nobox-nolabel` (Defaults to "return-bar" if not specified).
          type: string
        dropoff_methods_offered:
          description: >-
            Methods offered to the shopper. Used by Happy Returns for evaluating the user's experience.
            Can be one or more from the following `return-bar`, `mail`, `mail-nolabel`, `mail-nobox-nolabel`,
            `mail-shopper-provided`, `in-store`, `home-pickup`, or `other`.<br />
            
            <ul>
            
            <li><code>return-bar</code> - Shopper receives a QR code for box-free drop off at a Happy Returns' Return Bar</li>
            
            <li><code>mail</code> - Shopper receives a prepaid printable label</li>

            <li><code>mail-nolabel</code> - Shopper receives a QR code for pre-packaged drop off at a participating drop off location</li>
            
            <li><code>mail-nobox-nolabel</code> - Shopper receives a QR code for pre-packaged drop off at a The UPS Store® location</li>
            
            <li><code>mail-shopper-provided</code> - Shopper instructed to purchase their own shipping label</li>
            
            <li><code>home-pickup</code> - Return is picked up from shopper’s location</li>
            
            <li><code>retailer-store</code> - Shopper receives a QR code for drop off at a merchant store location</li>
            
            <li><code>other</code> - Other - Some other method not listed above</li>
            
            </ul>
          type: array
          items:
            type: string
        returning:
          description: The purchases being returned
          type: array
          items:
            $ref: '#/components/schemas/Instance'
      example:
        retailer_id: modern-retailer
        email: customer@example.com
        return_fee: 5.00 USD
        dropoff_method_id: return-bar
        dropoff_methods_offered:
          - return-bar
          - mail
          - mail-nolabel
          - mail-nobox-nolabel
          - mail-shopper-provided
          - home-pickup
          - retailer-store
          - other
        returning:
          -
            id: 12950087565378-3-1
            order_number: '290670'
            external_rma_id: RET2024XYZ999
            name: Nomadic Coast Short
            sku: nomshrts-1
            upc: SKDFHWEW-DKFD
            price: 50.00 USD
            images:
              - >-
                https://cdn.shopify.com/s/files/1/0552/3557/5874/products/olive_shorts.jpg?v=1661958339
            when: '2024-01-21T20:19:24Z'
            details:
              serialNumber: s243415236
              weight: 2.4
              weightUnit: lb
              brand: modern-retailer
              additional_scannable_codes:
                - sku-123
                - upc-456
            display:
              -
                label: Size
                value: '29'
              -
                label: Color
                value: Olive
            reason: damaged
            reason_type: damaged
            shipping_address:
              address1: 100 Willshire
              address2: ''
              city: Santa Monica
              country: United States
              latitude: 34.010929
              longitude: -118.491508
              province: California
              country_code: US
              province_code: CA
              zip_code: '90401'
            zip_code: '90401'
            refund_methods_offered:
              - refund
              - store credit
              - exchange - same price point
              - exchange - upsell
            label:
              note: "9482010898416007684584"
              barcode: "9482010898416007684584"
              representation: "code128"    
    CreateReturnRequestMailMailNoLabelAndMailNoBoxNoLabel:
      title: By Mail, Mail No Label, and Mail No Box No Label
      description: Create Return for Mail, Mail No Label, and Mail No Box No Label Request playload example
      required:
        - email
        - retailer_id
      type: object
      properties:
        retailer_id:
          description: >-
            The identifier of the retailer for the returning items. This needs to match an already
            existing retailer, cannot be arbitrary.
          type: string
        email:
          description: The email address on the order for sending email confirmations for the return
          type: string
        return_fee:
          description: Return fee amount with currency code
          type: string
        dropoff_method_id:
          description: >-
            Shopper selected dropoff method ID of the return, which can be one of the following `return-bar`, `in-store`, 
            `mail`, `mail-nolabel`, or `mail-nobox-nolabel` (Defaults to "return-bar" if not specified).
          type: string
        dropoff_methods_offered:
          description: >-
            Methods offered to the shopper. Used by Happy Returns for evaluating the user's experience.
            Can be one or more from the following `return-bar`, `mail`, `mail-nolabel`, `mail-nobox-nolabel`,
            `mail-shopper-provided`, `in-store`, `home-pickup`, or `other`.<br />
            
            <ul>
            
            <li><code>return-bar</code> - Shopper receives a QR code for box-free drop off at a Happy Returns' Return Bar</li>
            
            <li><code>mail</code> - Shopper receives a prepaid printable label</li>

            <li><code>mail-nolabel</code> - Shopper receives a QR code for pre-packaged drop off at a participating drop off location</li>

            <li><code>mail-nobox-nolabel</code> - Shopper receives a QR code for pre-packaged drop off at a The UPS Store® location</li>
            
            <li><code>mail-shopper-provided</code> - Shopper instructed to purchase their own shipping label</li>
            
            <li><code>home-pickup</code> - Return is picked up from shopper’s location</li>
            
            <li><code>retailer-store</code> - Shopper receives a QR code for drop off at a merchant store location</li>
            
            <li><code>other</code> - Other - Some other method not listed above</li>
            
            </ul>
          type: array
          items:
            type: string
        shipping_method_id:
          description: Shipping method ID of the retailer
          type: string
        mail_destination_address:
          description: Mail Destination address of the retailer
          type: object
          $ref: '#/components/schemas/MailDestinationAddress'
        custom_references:
          description: Mail label custom reference fields - used for select carriers.  Reach out to Happy Returns for more information.
          type: array
          items:
            $ref: '#/components/schemas/CustomReference'
        returning:
          description: The purchases being returned
          type: array
          items:
            $ref: '#/components/schemas/Instance'
        label:
          description: Allows customization of the Happy Returns Hub item label beyond the default available options. Hub item labels are not necessary for most headless implementations.
          type: object
          $ref: '#/components/schemas/Label'
        declared_value:
          description: Declared value of the items being shipped.
          type: string
      example:
        retailer_id: modern-retailer
        email: customer@example.com
        return_fee: 5.00 USD
        dropoff_method_id: mail-nolabel
        dropoff_methods_offered:
          - return-bar
          - mail
          - mail-nolabel
          - mail-nobox-nolabel
          - mail-shopper-provided
          - home-pickup
          - retailer-store
          - other
        shipping_method_id: "567"
        mail_destination_address:
          name: Modern retailer warehouse
          phone: 14247894567,
          address1: 2910 Wilshire Boulevard
          address2: ''
          city: Santa Monica
          country: United States
          province: California
          country_code: US
          province_code: CA
          zip_code: '90401'
        custom_references:
          - code: 'AJ'
            value: 'reference value 1'
            barcode_indicator: true
          -
            code: 'AT'
            value: 'reference value 2'
            barcode_indicator: false
        returning:
          -
            id: 12950087565378-3-1
            order_number: '290670'
            external_rma_id: RET2024XYZ999
            name: Nomadic Coast Short
            sku: nomshrts-1
            upc: SKDFHWEW-DKFD
            price: 50.00 USD
            images:
              - >-
                https://cdn.shopify.com/s/files/1/0552/3557/5874/products/olive_shorts.jpg?v=1661958339
            when: '2024-01-21T20:19:24Z'
            details:
              serialNumber: s243415236
              weight: 2.4
              weightUnit: lb
              brand: modern-retailer
              additional_scannable_codes:
                - sku-123
                - upc-456
            display:
              -
                label: Size
                value: '29'
              -
                label: Color
                value: Olive
            reason: damaged
            reason_type: damaged
            shipping_address:
              address1: 100 Willshire
              address2: ''
              city: Santa Monica
              country: United States
              latitude: 34.010929
              longitude: -118.491508
              province: California
              country_code: US
              province_code: CA
              zip_code: '90401'
            zip_code: '90401'
            refund_methods_offered:
                - refund
                - store credit
                - exchange - same price point
                - exchange - upsell
            label:
              note: "9482010898416007684584"
              barcode: "9482010898416007684584"
              representation: "code128"
        declared_value: "100.00 USD"
    InternalServerError:
      description: Error sent when there was an server error
      type: string
      example: Bad request
