> ## 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.
# Sendcloud template
The Sendcloud Custom Action connects your Agent to Sendcloud so it can retrieve order and shipment information and use it when answering customer questions.
This setup includes:
* A predefined OpenAPI schema for Sendcloud
* Basic authentication
* The required Sendcloud 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**
`Sendcloud Order status Retrieval`
**Description**
`This action lets you get status information from your orders and use it in your chatbot when customers ask for it.`
**BaseURL**
`https://panel.sendcloud.sc/api/v2`
### Authentication
For **Authorization Header**, select **Basic**.
**Username**
`public_key`
Replace this with your Sendcloud public key.
**Password**
`secret_key`
Replace this with your Sendcloud secret key.
### Health check
**Health check URL**
`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 Sendcloud schema into the **Schema** field:
```text theme={null}
openapi: 3.0.0
info:
title: Sendcloud Parcel and Order Tracking API
description: API for retrieving detailed tracking information of parcels and orders
version: 1.0.0
servers:
- url: https://api.sendcloud.com/v1
description: Sendcloud API server
paths:
/tracking/{tracking_number}:
get:
summary: Retrieve tracking information of a parcel
description: |
This endpoint retrieves detailed tracking information of a parcel based on the provided tracking number.
It returns information such as the unique parcel ID, carrier details, delivery status, and tracking URLs.
This data can be used by customers to track the status of their parcel delivery.
parameters:
- in: path
name: tracking_number
description: The tracking number associated with the parcel
required: true
schema:
type: string
responses:
'200':
description: |
Successful response. Returns detailed tracking information of the parcel.
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelResponse'
'404':
description: Not Found
content:
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitErrorResponse'
/orders/:
get:
summary: Retrieve order information by order number
description: |
This endpoint retrieves detailed order information based on the provided order number.
It returns data such as order details, payment status, shipping address, and other relevant information.
parameters:
- in: query
name: order_number
description: The unique order number of the order
required: true
schema:
type: string
responses:
'200':
description: |
Successful response. Returns detailed information of the order.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'404':
description: Order not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitErrorResponse'
components:
schemas:
ParcelResponse:
type: object
properties:
parcel_id:
type: string
description: Unique ID for the parcel
carrier_code:
type: string
description: A carrier represented by a Sendcloud code
example: postnl
created_at:
type: string
format: date-time
description: |
Timestamp in ISO format indicating when the parcel was first tracked by Sendcloud’s systems
example: "2022-01-25T14:42:03.277703+00:00"
carrier_tracking_url:
type: string
description: Link to the carrier’s Tracking page for this parcel
example: "https://tracking.sendcloud.sc/forward?carrier=postnl&code=3SYZXG132912330&destination=NL&lang=en-us&source=NL&type=parcel&verification=5611+EM&servicepoint_verification=&created_at=2022-01-25"
sendcloud_tracking_url:
type: string
description: Link to Sendcloud’s Tracking page for this parcel
example: "https://my-bakery.shipping-portal.com/tracking/?country=nl&tracking_number=3SYZXG132912330&postal_code=5611+EM"
is_return:
type: boolean
description: |
Indicates whether this parcel is a return (incoming) shipment to the merchant
example: false
is_to_service_point:
type: boolean
description: |
Indicates whether this parcel is delivered to a service point
example: false
is_mail_box:
type: boolean
description: |
Indicates whether this parcel will be delivered to a mail box
example: false
expected_delivery_date:
type: string
format: date
description: |
Date when the parcel is expected to be delivered (estimate, no timestamp)
example: "2022-01-26"
statuses:
type: array
description: List of shipping statuses for the parcel
items:
$ref: '#/components/schemas/ParcelStatus'
ParcelStatus:
type: object
properties:
carrier_update_timestamp:
type: string
format: date-time
description: |
Timestamp (ISO format) indicating when the carrier moved the parcel to this status
example: "2022-01-25T16:42:03.277703+00:00"
parcel_status_history_id:
type: string
description: ID of the historical status
example: "1270787363"
parent_status:
type: string
description: Current delivery status of the parcel
example: delivered
carrier_code:
type: string
description: A carrier represented by a Sendcloud code
example: postnl
carrier_message:
type: string
description: |
Status description specified by the carrier, more detailed than parent_status
example: Shipment delivered, no signature
OrderResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the order
order_number:
type: string
description: Unique order number
created_at:
type: string
format: date-time
description: Timestamp when the order was created
modified_at:
type: string
format: date-time
description: Timestamp when the order was last modified
order_details:
$ref: '#/components/schemas/FlatOrderDetails'
payment_details:
$ref: '#/components/schemas/FlatPaymentDetails'
customs_details:
$ref: '#/components/schemas/FlatCustomsDetails'
shipping_address:
$ref: '#/components/schemas/ShippingAddress'
FlatOrderDetails:
type: object
properties:
integration_id:
type: integer
status_code:
type: string
status_message:
type: string
order_created_at:
type: string
format: date-time
order_updated_at:
type: string
format: date-time
order_items:
type: array
items:
$ref: '#/components/schemas/FlatOrderItem'
FlatOrderItem:
type: object
properties:
name:
type: string
weight_value:
type: number
weight_unit:
type: string
quantity:
type: integer
unit_price_value:
type: number
unit_price_currency:
type: string
total_price_value:
type: number
total_price_currency:
type: string
delivery_handover_at:
type: string
format: date-time
delivery_deliver_at:
type: string
format: date-time
FlatPaymentDetails:
type: object
properties:
is_cash_on_delivery:
type: boolean
total_price_value:
type: number
total_price_currency:
type: string
status_code:
type: string
status_message:
type: string
discount_value:
type: string
discount_currency:
type: string
insurance_value:
type: string
insurance_currency:
type: string
freight_value:
type: string
freight_currency:
type: string
other_value:
type: string
other_currency:
type: string
FlatCustomsDetails:
type: object
properties:
commercial_invoice_number:
type: string
shipment_type:
type: string
ShippingAddress:
type: object
properties:
name:
type: string
address_line_1:
type: string
house_number:
type: string
postal_code:
type: string
city:
type: string
country_code:
type: string
ErrorResponse:
type: object
properties:
Error:
type: object
properties:
Code:
type: string
description: Error code indicating the type of error
example: NoSuchKey
Message:
type: string
description: Detailed error message describing the issue
example: The specified key does not exist.
Key:
type: string
description: Key associated with the error, if applicable
example: v2/103/AHDJ290827.json
RequestId:
type: string
description: ID of the request associated with the error
example: D4W06G972XFZYM6
HostId:
type: string
description: ID of the host associated with the error
example: icweEyuSLyXQoikNKR5ndkrbCZL55s7NbFIYbLn25OQqKn1REF1RE5YOUd7XHRUlDSWzOY=
RateLimitErrorResponse:
type: object
properties:
status:
type: integer
message:
type: string
```
Click **Validate** to check the schema.
### Example in Watermelon
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 information from Sendcloud.
## 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 Sendcloud credentials | Check your public key and secret key. |
| **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. |