The ReturnGO API enables you to dynamically assign a return store location for approved RMAs. This allows you to automate return routing to different store locations and streamline the return process without manual input.
For more information about the API, check out the article about the ReturnGO API and its abilities.
Capabilities
Using the API to dynamically assign a return store location, you can:
- Automatically assign a return store location based on custom rules defined on your server.
- Receive full order, RMA, customer, and item details in the API request.
- Generate a return shipping label using the return address provided by your server upon RMA approval.
- Protect your endpoint using an Authorization header or other supported authentication methods.
Limitations
- The API request does not include latitude or longitude.
Tip: If you need geographic coordinates, you can save them as custom order attributes before the customer initiates a return. Your server can then retrieve them using the order ID included in the API request.
Requirements
Note: This feature can be enabled upon request.
To use this setup, you’ll need the following credentials:
- API username
- API password
- Endpoint URL
See full documentation of endpoints, webhooks, and more in the ReturnGO API Documentation.
How It Works
Once the Custom Dynamic Location is enabled and the integration is configured, the return store location is determined when an RMA is approved.
When an RMA is approved, either automatically through the portal or manually via the dashboard:
1. ReturnGO sends a request to your configured server endpoint to retrieve the return store location.
Note: ReturnGO includes the full order and RMA details in the API request. However, your server can rely only on the order ID if the other data is not needed.
2. Your server responds with a return address.
3. ReturnGO uses the provided address to generate a return shipping label.
4. The label is then sent to the customer.
Linking the Custom Dynamic Location Integration
After the Custom Dynamic Location is enabled on your account, you need to link the integration to ReturnGO.
To link the Custom Dynamic Location:
1. Go to Settings > Integration > Products & Services.
2. Click on +ADD PRODUCT OR SERVICE.
3. Choose Custom Dynamic Location from the drop-down list.
4. Click on the check mark.
5. Enter your credentials.
Tip: It is recommended to use an Authorization header (e.g., with a token or API key) for authentication.
6. Add your Full endpoint URL.
7. Click CONNECT.
Payload Structure
The following sample payloads show the expected request from ReturnGO and the response your server should return.
Note: You must follow this structure when implementing the setup, as it is the format ReturnGO uses to communicate with your server.
Sample API Request Payload
{
"rmaSummary": {
"rmaId": "RMA123456",
"status": "Pending",
"createdAt": "2024-03-20T10:00:00Z"
},
"customer": {
"customerId": "123049585",
"customerAddress": {
"name": "Home Address",
"street1": "123 Main Street",
"street2": "Apt 4B",
"city": "New York",
"stateCode": "NY",
"zip": "10001",
"countryCode": "US",
"phone": "+1 (212) 555-0123",
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe"
}
},
"orderDetail": {
"orderName": "Order #1001",
"orderId": "1001",
"paymentGateways": [
{
"name": "Stripe",
"amount": 100.00,
"currency": "USD"
}
],
"items": [
{
"shopLineItemId": "LI123",
"shopProductId": "P123",
"variantId": "V123",
"sku": "SKU123",
"barcode": "BAR123",
"paidPrice": {
"amount": 50.00,
"currency": "USD"
},
"paidTax": {
"amount": 5.00,
"currency": "USD"
},
"taxIncluded": true,
"displayName": "Product Name",
"tags": ["tag1", "tag2"],
"imageUrl": "https://example.com/image.jpg"
}
],
"tags": ["tag1", "tag2"]
},
"items": [
{
"shopLineItemId": "LI123",
"shopProductId": "P123",
"variantId": "V123",
"sku": "SKU123",
"barcode": "BAR123",
"paidPrice": {
"amount": 50.00,
"currency": "USD"
},
"paidTax": {
"amount": 5.00,
"currency": "USD"
},
"taxIncluded": true,
"displayName": "Product Name",
"tags": ["tag1", "tag2"],
"imageUrl": "https://example.com/image.jpg",
"returnReason": "Wrong size",
"resolutionType": "RefundToPaymentMethod",
"restockingFee": 5.00,
"shipmentFee": 10.00,
"returnFee": 2.00,
"shipmentId": "SHIP123",
"extendedReason": "Item doesn't fit as expected",
"reducedAmount": 0,
"refundedMoney": [
{
"amount": 50.00,
"currency": "USD"
}
],
"storeCurrencyRefundedMoney": {
"amount": 50.00,
"currency": "USD"
},
"exchangeItems": [
{
"productId": "P124",
"variantId": "V124",
"sku": "SKU124"
}
],
"productCaseId": "CASE123",
"warehouseId": "WH123"
}
]
}
Note: The API request and response payloads both include the postcode (zip code) as part of the return address.
Sample Response Payload
{
"address": {
"name": "Home Address",
"street1": "123 Main Street",
"street2": "Apt 4B",
"city": "New York",
"stateCode": "NY",
"zip": "10001",
"countryCode": "US",
"phone": "+1 (212) 555-0123",
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe"
}
}
Note: The address returned by your server is used as-is to generate the return shipping label. ReturnGO does not modify or validate the address.