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.2 -
Create Return Location
actionCreates a new return location (warehouse or depot address) for an account. Required:accountId,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.1 -
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.3 -
Get Draft Return Orders
actionGets a list of draft return orders for the given account. See the documentationRead-onlyv0.0.2 -
Get Return Locations
actionGets a list of return locations for the given account. See the documentationRead-onlyv0.0.2 -
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.3 -
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.3 -
Get Return Orders
actionGets a list of return orders for the given account. See the documentationRead-onlyv0.0.2 -
Get Return Reasons
actionGets a list of return reasons for the given account. See the documentationRead-onlyv0.0.2 -
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.3 -
Get Return Requests
actionGets a list of return requests for the given account. See the documentationRead-onlyv0.0.2 -
List Shipping Products
actionReturns all shipping product options available in Returnista, including carrier integrations, label types, and product codes. See the documentationRead-onlyv0.0.1 -
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.2 -
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 both an Account ID (from your Returnista dashboard settings) and a Return Order ID. Note: this triggers an immediate send — there is no scheduling or preview step. See the documentationWritev0.0.2 -
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.3
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.2 -
New Return Order Confirmed (Instant)
triggerEmit new event when a return order is confirmed. See the documentationInstantv0.0.2 -
New Return Order Created (Instant)
triggerEmit new event when a new return order is created. See the documentationInstantv0.0.2 -
New Sales Order Approved or Denied (Instant)
triggerEmit new event when a sales order is approved or denied. See the documentationInstantv0.0.2 -
New Shipment Label Created (Instant)
triggerEmit new event when a new shipment label is created. See the documentationInstantv0.0.2 -
New Shipment Received Tracking Updates (Instant)
triggerEmit new event when a shipment receives tracking updates. See the documentationInstantv0.0.2 -
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.2
- App slug
- returnista
- Authentication
- API key
- Categories
- Commerce
- Actions
- 15
- Triggers
- 7
- API proxy
- Available