CONNECT APP
Build with Returnista
Commerce
- API key
MCP
Give your agent Returnista tools
Every Returnista action is exposed as an MCP tool on Pipedream's remote server. Point a client at it with your end user's ID and Connect resolves that user's Returnista account for each tool call — you store no tokens.
// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
new URL("https://remote.mcp.pipedream.net/v3"),
{
requestInit: {
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
"x-pd-app-slug": "returnista",
},
},
},
)
const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)
const { tools } = await mcp.listTools()
// e.g. run Create Draft Return Order:
const result = await mcp.callTool({
name: "returnista-create-draft-return-order",
arguments: {
consumerId: "Consumer ID",
purchaseId: "Purchase ID",
},
})# access_token: mint a short-lived token with the Connect SDK — see the MCP guide
headers = {
"Authorization": f"Bearer {access_token}",
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", # any stable ID for this user in your system
"x-pd-app-slug": "returnista",
}
async with streamablehttp_client("https://remote.mcp.pipedream.net/v3", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
# e.g. run Create Draft Return Order:
result = await session.call_tool("returnista-create-draft-return-order", {
"consumerId": "Consumer ID",
"purchaseId": "Purchase ID",
})API PROXY
Call the Returnista API directly
For an endpoint with no pre-built tool, the Connect proxy forwards your request to the Returnista API with the connected user's credentials attached. You store no tokens and write no refresh logic.
const resp = await pd.proxy.get({
externalUserId: "{external_user_id}", // any stable ID for this user in your system
accountId: "apn_xxxxxxx",
url: "https://core.returnista.com/api/v0/return-reasons",
})
// Any allowed Returnista endpoint works here. Pipedream attaches the
// connected account's credentials to the outgoing request.# The path segment is the target URL, URL-safe base64 encoded:
# https://core.returnista.com/api/v0/return-reasons
curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly9jb3JlLnJldHVybmlzdGEuY29tL2FwaS92MC9yZXR1cm4tcmVhc29ucw?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
-H "Authorization: Bearer {access_token}" \
-H "x-pd-environment: production"SDK
Run Returnista actions from your backend
Connect a user's Returnista account once, then run Create Draft Return Order on their behalf from your own code — TypeScript, Python, or plain HTTP.
import { PipedreamClient } from "@pipedream/sdk"
const pd = new PipedreamClient({
projectId: process.env.PIPEDREAM_PROJECT_ID!,
clientId: process.env.PIPEDREAM_CLIENT_ID!,
clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
projectEnvironment: "production",
})
const result = await pd.actions.run({
id: "returnista-create-draft-return-order",
externalUserId: "{external_user_id}", // any stable ID for this user in your system
configuredProps: {
returnista: { authProvisionId: "apn_xxxxxxx" },
consumerId: "Consumer ID",
purchaseId: "Purchase ID",
},
})from pipedream import Pipedream
pd = Pipedream(
client_id="{oauth_client_id}",
client_secret="{oauth_client_secret}",
project_id="{project_id}",
project_environment="production",
)
result = pd.actions.run(
id="returnista-create-draft-return-order",
external_user_id="{external_user_id}", # any stable ID for this user in your system
configured_props={
"returnista": {"authProvisionId": "apn_xxxxxxx"},
"consumerId": "Consumer ID",
"purchaseId": "Purchase ID",
},
)curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
-H "Content-Type: application/json" \
-H "X-PD-Environment: production" \
-H "Authorization: Bearer {access_token}" \
-d '{
"external_user_id": "{external_user_id}",
"id": "returnista-create-draft-return-order",
"configured_props": {
"returnista": { "authProvisionId": "apn_xxxxxxx" },
"consumerId": "Consumer ID",
"purchaseId": "Purchase ID"
}
}'TOOLS
Returnista actions
On-demand operations your product or agent can configure and run on behalf of a connected user.
-
Create Draft Return Order
actionCreates a new draft return order for a consumer. Draft return orders are pending merchant review before being accepted or rejected. Use Process Draft Return Order to accept or reject the created draft. See the documentationWritev0.0.3 -
Create Return Location
actionCreates a new return location (warehouse or depot address) for an account. Required:name,companyName,phoneNumber,street,houseNumber,city,postalCode,countryCode(ISO 3166-1 alpha-2, e.g.NL,DE,GB,US). Optional:suffix,stateProvinceCode,attention,contactName. To update a location after creation, use Update Return Location with the returned ID. See the documentationWritev1.0.2 -
Get Consumer Purchases
actionGets the purchase history for a consumer by their consumer ID. Useful for support workflows to understand what a consumer has purchased before they initiated a return. To find a consumer ID, use Get Return Orders withexpand: ["consumer"]on a related return order — the consumer object will include the ID. See the documentationRead-onlyv0.0.4 -
Get Draft Return Orders
actionGets a list of draft return orders for the given account. See the documentationRead-onlyv0.0.3 -
Get Return Locations
actionGets a list of return locations for the given account. See the documentationRead-onlyv0.0.3 -
Get Return Order
actionGets the full details of a single return order by ID. Useexpandto inline related objects (consumer, shipments, returnRequests) in one call instead of making separate requests. To find a return order ID, use Get Return Orders first. To view the email communications for a return order, use Get Return Order Emails. See the documentationRead-onlyv0.0.4 -
Get Return Order Emails
actionGets all email communications associated with a return order. Useful for support and audit workflows to see what emails were sent to the consumer during the return process. To find a return order ID, use Get Return Orders first. See the documentationRead-onlyv0.0.4 -
Get Return Orders
actionGets a list of return orders for the given account. See the documentationRead-onlyv0.0.3 -
Get Return Reasons
actionGets a list of return reasons for the given account. See the documentationRead-onlyv0.0.3 -
Get Return Request
actionGets the full details of a single return request by ID. Return requests contain item-level information: purchase order number, return reason, requested resolution (refund, exchange, etc.). To find a return request ID, use Get Return Requests first. See the documentationRead-onlyv0.0.4 -
Get Return Requests
actionGets a list of return requests for the given account. See the documentationRead-onlyv0.0.3 -
List Shipping Products
actionReturns all shipping product options available in Returnista, including carrier integrations, label types, and product codes. See the documentationRead-onlyv0.0.2 -
Process Draft Return Order
actionAccepts or rejects a draft return order. Draft return orders are created when a consumer initiates a return and are pending merchant review. Setactiontoacceptto approve the return (this triggers shipment label creation) orrejectto decline it. Use Get Return Orders withfilter: "status:draft"to find draft order IDs. See the documentationWritev0.0.3 -
Resend Confirmation Email
actionResends the return confirmation email to the consumer for an existing return order. Use this when a consumer did not receive their original confirmation, when an email bounced, or to re-trigger a notification after a return order is updated. To look up a return order ID, use Get Return Orders or Get Return Order first. To view the email history before resending, use Get Return Order Emails. Requires a Return Order ID. Note: this triggers an immediate send — there is no scheduling or preview step. See the documentationWritev0.0.3 -
Update Return Location
actionUpdates an existing return location for an account. All fields are optional — provide only the ones you want to change. At least one field must be provided. To find the return location ID, use Get Return Locations. Use a two-letter ISO 3166-1 alpha-2 country code forcountryCode(e.g.,NL,DE,GB,US). See the documentationWritev0.0.4
EVENTS
Returnista triggers
Event sources your backend can deploy for users and receive through a webhook.
-
New Return Order Completed (Instant)
triggerEmit new event when a return order is completed. See the documentationInstantv0.0.3 -
New Return Order Confirmed (Instant)
triggerEmit new event when a return order is confirmed. See the documentationInstantv0.0.3 -
New Return Order Created (Instant)
triggerEmit new event when a new return order is created. See the documentationInstantv0.0.3 -
New Sales Order Approved or Denied (Instant)
triggerEmit new event when a sales order is approved or denied. See the documentationInstantv0.0.3 -
New Shipment Label Created (Instant)
triggerEmit new event when a new shipment label is created. See the documentationInstantv0.0.3 -
New Shipment Received Tracking Updates (Instant)
triggerEmit new event when a shipment receives tracking updates. See the documentationInstantv0.0.3 -
New Tracking Update Delivered (Instant)
triggerEmit new event when a tracking update is received and the shipment status changes to delivered. See the documentationInstantv0.0.3
- App slug
- returnista
- Authentication
- API key
- Categories
- Commerce
- Actions
- 15
- Triggers
- 7
- API proxy
- Available