Retrieving Returns
Sales returns / refunds with lines.
Use GET /api/v1/returns to page through every record in your organization, or GET /api/v1/returns/{id} to fetch a single record with its related data. The id is a UUID, and a 404 means it doesn't exist in your organization.
API Endpoint
GET
/api/v1/returns
GET
/api/v1/returns/{id}
Current Use Cases
Process refunds in accounting
Send returns with their lines to your accounting tool so refunds and credits are recorded.
Restock returned items
See which items came back so they get counted back into stock or written off.
Track return rates
Group returns by customer or product to spot quality issues early.
Link returns to orders
Filter by sales_order_id to see the full history of an order, from sale to return.
Required Headers
Every request must include the following:
Header Key
Description
org-api-key
Your Organization API key. Contact Cloudbox Support For Access: support@cloudboxapp.com.
user-api-key
Your User API Key
Requests missing either header will return 401 Unauthorized
Example Request
bash
curl -X GET "https://app.cloudboxapp.com/api/v1/returns?limit=100" \
-H "org-api-key: YOUR_ORG_API_KEY" \
-H "user-api-key: YOUR_USER_API_KEY" \
-H "Accept: application/json"
Response Schema
Column
Type
Description
Filters
Errors
Cloudbox uses standard HTTP status codes to indicate API success or failure:
- 200–299 – Request succeeded
- 400 – Bad request (missing parameters, invalid values)
- 401 – Unauthorized (missing or invalid API keys)
- 404 – Resource not found
- 429 – Too many requests (rate limited)