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

# Returnless template

The Returnless Custom Action connects your Agent to Returnless so it can retrieve return and order status information and use it when answering customer questions.

This setup includes:

* A predefined OpenAPI schema for Returnless
* API key authentication
* The required Returnless API BaseURL
* A health check configuration

After setting up the Action, you can validate it, activate it, and test it in the Playground.

## Set up the action

1. Go to **Actions** in Watermelon.
2. In the **Actions catalog**, click **Custom action**.
3. Click **Create new Action**.
4. Fill in the fields below.

### General details

**Action name**<br />`Returnless order status`

**Description**<br />`This action lets you get status information from your orders and use it in your chatbot when customers ask for it.`

**BaseURL**<br />`https://api-v2.returnless.com/2023-01`

### Authentication

For **Authorization Header**, select **API key**.

For **Auth Type**, select **Bearer**.

**Token**<br />`YOUR-API-KEY`

Replace this with your Returnless API key.

### Health check

**Health check URL**<br />`https://www.yourdomain.com/health_check`

Replace this URL with the health check endpoint you want Watermelon to use.

**Instruction**

> You should respond with the following message or a similar variation: Sorry, something went wrong on our end. Can I assist you with anything else? Please let me know how I can help.

### Schema

Paste the Returnless schema into the **Schema** field:

```text theme={null}
openapi: 3.0.0
info:
  title: Returnless Chatbot Integration
  version: 1.0.0
  description: Integration between Returnless and the chatbot to enhance product efficiency
servers:
  - url: https://api-v2.returnless.com


paths:
  /return-orders/{return-order}:
    get:
      summary: Get product status
      description: Retrieve product status by return number
      parameters:
        - name: return-order
          in: path
          required: true
          description: The return number in Returnless 
          example: RTR123456
          schema:
            type: string
            pattern: "RTR\\d{6}$"
      responses:
        '200':
          description: Return status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
        '400':
          description: No return with that ID found
        '404':
          description: No return ID given


components:
  schemas:
    ReturnResponse:
      type: object
      properties:
        return_id:
          type: string
          example: "948191"
        return:
          type: string
          example: "RENL1641091121"
        status:
          type: string
          example: "processing"
        reference:
          type: string
          example: "ORD000123"
        order_id:
          type: string
          example: "124006"
        order_date:
          type: string
          format: date-time
          example: "2021-01-10 10:46:27"
        return_date:
          type: string
          format: date-time
          example: "2021-01-20 11:52:42"
        updated_at:
          type: string
          format: date-time
          example: "2021-01-21 22:19:58"
        form:
          type: string
          example: "5919"
        customer_id:
          type: string
          example: "58179"
        customer_email:
          type: string
          format: email
          example: "pieter@returnless.com"
        request_id:
          type: string
          example: "481049"
        shipping_description:
          type: string
          example: "PostNL inleveren bij pakketpunt"
        tracking_number:
          type: string
          example: "3STRVL58192041"
        tracking_status_id:
          type: string
          example: "1000"
        tracking_status:
          type: string
          example: "Ready to Send"
        tracking_url:
          type: string
          format: uri
          example: "https://jouw.postnl.nl/track-and-trace/3STRVL58192041-NL-5611NV"
        shipping_label_link:
          type: string
          format: uri
          example: "https://www.returnless.com/shippinglabel/index/?scid=3SRLSS001989339&hash=hsFMhN544bhKD57wk9QDJxjsUJ"
        files:
          $ref: '#/components/schemas/FilesArray'
        return_questions:
          $ref: '#/components/schemas/ReturnQuestionsArray'
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        return_notes:
          $ref: '#/components/schemas/ReturnNotesArray'
        returned_products:
          $ref: '#/components/schemas/ReturnedProductsArray'


    FilesArray:
      type: array
      items:
        type: string
        format: uri
        example: "https://www.retourneren.nl/sales/download/downloadCustomOption/id/8304498/key/1f96k3FAZG9exk6"


    ReturnQuestionsArray:
      type: array
      items:
        type: object
        properties:
          option_id:
            type: string
            example: "46363"
          label:
            type: string
            example: "Please describe the damage."
          value:
            type: string
            example: "There is a stain on the t-shirt."


    BillingAddress:
      type: object
      properties:
        first_name:
          type: string
          example: "Pieter"
        last_name:
          type: string
          example: "Post"
        postcode:
          type: string
          example: "5611NV"
        country:
          type: string
          example: "NL"
        city:
          type: string
          example: "Eindhoven"
        address1:
          type: string
          example: "PCzn Hooftlaan"
        address2:
          type: string
          example: "14"
        addition:
          type: string
          example: ""


    ReturnNotesArray:
      type: array
      items:
        type: object
        properties:
          message:
            type: string
            example: "The status has been changed from Open to Approved"
          name:
            type: string
            example: "Returnless Support"
          quote_id:
            type: integer
            example: 408516
          created_at:
            type: string
            format: date-time
            example: "2022-05-13 13:29:45"


    ReturnedProductsArray:
      type: array
      items:
        type: object
        properties:
          return_item_id:
            type: string
            example: "1458191"
          product_id:
            type: string
            example: "1007"
          qty_ordered:
            type: string
            example: "1.0000"
          qty_returned:
            type: string
            example: "1.0000"
          qty_received:
            type: string
            example: "0.0000"
          order_product_id:
            type: string
            example: "153397"
          name:
            type: string
            example: "Samsonite S'Cure Spinner 55 navy blue capri"
          title_name:
            type: string
            example: "Samsonite S'Cure Spinner 55"
          model:
            type: string
            example: "trvl-01598592"
          article_code:
            type: string
            example: "495398926"
          cost:
            type: string
            example: "87.50"
          images:
            type: array
            items:
              type: object
              properties:
                http_path:
                  type: string
                  format: uri
                  example: "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
          url:
            type: string
            format: uri
            example: "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html"
          u_brand:
            type: string
            example: "Samsonite"
          ean:
            type: string
            example: "890128492109899"
          reason_id:
            type: string
            example: "2"
          reason:
            type: string
            example: "Size too small"
          back_to_stock:
            type: string
            example: "1"
          remarks:
            type: string
            example: ""
```

Click **Validate** to check the schema.

### Example in Watermelon

<Frame>
  <img src="https://mintcdn.com/watermelon/U1o80ZmdmQTd06X6/images/Returnless-action-template.png?fit=max&auto=format&n=U1o80ZmdmQTd06X6&q=85&s=4674fba01afdfaad792108a380d57d39" alt="Returnless Action Template" width="3838" height="1842" data-path="images/Returnless-action-template.png" />
</Frame>

When everything is configured correctly, click **Save** and then **Activate**.

Finally, test the Action in the **Playground** to make sure your Agent can retrieve the expected Returnless data.

## Editing an Action Template

After setting up an Action, you can adjust it to your use case. For example, you can add endpoints to the schema, change parameters, or update the name and description.

Be careful when changing authentication settings or existing endpoints, as this can prevent the Action from connecting to the API.

## Troubleshooting

| Issue                                        | Likely cause                            | What to check                                             |
| :------------------------------------------- | :-------------------------------------- | :-------------------------------------------------------- |
| **Validation failed**                        | Invalid OpenAPI schema                  | Check the schema for missing or unsupported fields.       |
| **401 Unauthorized**                         | Incorrect credentials                   | Check your API key, token, username, or password.         |
| **404 Not Found**                            | Incorrect endpoint                      | Check the BaseURL and endpoint path.                      |
| **Action does not return the expected data** | Schema or parameter mismatch            | Check the endpoint parameters and API response structure. |
| **Health check fails**                       | Health check endpoint cannot be reached | Check the Health check URL and authentication.            |