> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.shipbob.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_mcp/server. # Setup ShipBob Returns > Getting Started with ShipBob Returns ShipBob Returns gives your customers a self-service returns portal and gives you a dashboard to review every return and exchange request. This guide walks through the full setup flow, from first sign-in to sharing your live portal with customers. Most merchants can complete setup in about 20 minutes. ## Before You Begin Make sure you have: * A ShipBob account with Merchant Portal access * A Shopify store and Shopify admin credentials * A brand logo to upload to the portal * A ShipBob Personal Access Token (PAT), or permission to create one during setup * Optional access to your DNS provider if you want to use a custom returns domain such as `returns.yourbrand.com` ## What ShipBob Returns Does Once configured, ShipBob Returns helps you: * Let customers start returns through a branded self-service portal * Create return orders (RMAs) in ShipBob * Generate return labels * Route returns back to the correct fulfillment center * Offer refunds, exchanges, replacements, or store credit based on your return policy * Automate approval, rejection, and special handling with Flows * Keep return statuses synchronized between ShipBob Returns and ShipBob ## Recommended Setup Order For the smoothest launch, complete setup in this order: 1. Sign in to ShipBob Returns 2. Connect your Shopify store 3. Brand the portal and email experience 4. Add your ShipBob Personal Access Token 5. Confirm where returns should be routed 6. Configure your return policy, return window, and return reasons 7. Set up Flows for any automation or special handling you need 8. Submit one test return before sharing the portal publicly 9. Share your returns portal with customers *** ## Step 1: Sign In 1. Log in to ShipBob the way you normally do, at **[https://web.shipbob.com/app/merchant/#/dashboard](https://web.shipbob.com/app/merchant/#/dashboard)**. 2. In a new tab, go to **returns.shipbob.app** and click **Continue with ShipBob**. 3. Scroll down and click **Allow and Install** to authorize ShipBob Returns. The first person from your organization may be asked to accept the Beta Application Terms of Service. This only needs to be completed once per organization. *** ## Step 2: Connect the Shopify App 1. Click **Connect to Shopify**. 2. Install the ShipBob Returns app when Shopify prompts you. Once connected, you land back on the **Returns** page. This connection allows ShipBob Returns to read order data from Shopify so customers can look up purchases, confirm item eligibility, and start a return using the details on their order. *** ## Step 3: Brand Your Returns Portal Go to **Customizations** to make the portal match your brand: * **Logo** and **favicon** uploads * **Accent color** (hex code) used for buttons and highlights * **Company name** and **header text** shown at the top of the portal Your returns portal is live at: ```text https://your-store.returns.shipbob.app ``` where `your-store` is your store's name. You can preview it anytime from the dashboard. ### Use Your Own Domain (recommended) If you would like customers to see a domain like `returns.yourbrand.com`: 1. In **Customizations**, enter your domain in **Your custom domain**. 2. Add the CNAME record shown on screen at your DNS provider. 3. Click **Check status** (or **Verify DNS**) once the record is in place. DNS changes can take a few minutes to propagate. Once verified, all portal links and customer emails automatically use your custom domain. Each DNS provider can differ in how you add a subdomain. If anything is not working, reach out to your ShipBob rep. ### Send from your own domain (recommended) 1. In **Customizations**, enter your domain and also your send-from address (for example, `returns@yourbrand.com`). 2. Add the DNS records shown on screen (these authenticate your domain so emails land in the inbox, not spam). 3. Verify the records from the same screen. ## Step 4: Connect ShipBob with a Personal Access Token Your ShipBob PAT lets the returns platform create return orders (RMAs), purchase return shipping labels, and track return shipments back to your fulfillment center. **Create the token in ShipBob:** 1. In the ShipBob Merchant Portal, go to **Integrations > API Tokens**. 2. Create a new Personal Access Token and copy it. The token looks like a long string of 64 letters and numbers followed by a hyphen and a number (for example, `1DF869E3...DDB5-1`). **Add the token in ShipBob Returns:** 1. Go to **Settings > Integrations > Personal access token**. 2. Paste the full token exactly as copied - do not add a "Bearer" prefix or any extra characters. 3. Click **Save**. The token is stored securely and displayed masked from then on. 4. Click **Test Connection**. This verifies the token works and automatically detects your ShipBob channel, so you do not need to look it up manually. Once the token is saved, ShipBob Returns automatically: * Subscribes to ShipBob return status updates, so return progress appears in your dashboard in real time * Syncs your product catalog, matching your Shopify SKUs to ShipBob inventory so returned items are routed correctly > **Note:** If a SKU cannot be matched, it will be flagged in your dashboard. You can re-run the match anytime with the **Auto-sync** button in the same settings section. Before moving on, make sure **Test Connection** succeeds. If it does not, returns cannot be created or routed correctly. ## Step 5: Choose Where Returns Are Sent Under **Settings**, configure your return destination: * **Return to origin warehouse** - each return is sent back to the ShipBob fulfillment center that originally shipped the order. This is the recommended option for most merchants. * **Default / backup warehouse** - choose a specific ShipBob fulfillment center to receive returns. This is also used as the fallback when the origin warehouse cannot be determined. If ShipBob Returns cannot determine the original fulfillment center for an order, it uses the backup warehouse automatically. If you want tighter operational control, set the backup warehouse intentionally instead of leaving it as a default choice. ## Step 6: Set Your Return Policy In **Settings**, review the core return policy options: * **Return window** - how many days after shipment a customer can start a return * **Require order to be fulfilled** - block returns until the order has shipped * **Auto-approve return labels** - send labels automatically or hold returns for review * **Refunds, exchanges, replacements, and store credit** - choose which outcomes customers can request * **Store credit bonus** - encourage store credit by offering a higher value than a cash refund * **Non-returnable product tags** and **excluded SKUs** - block certain products from being returned through the portal * **Condition questions** - ask customers whether an item was opened, worn, or damaged, and optionally require notes or photos For the full policy breakdown, including return reasons, return-window behavior, hazmat handling, and guidance on manual review vs. auto-approval, see [Configure Return Policies](/labs/returns-policy). ## Step 7: Automate with Flows Flows let you automate exceptions that would otherwise require manual review. Use them to: * Auto-approve low-risk returns * Auto-reject returns that fall outside your policy * Route damaged-item claims into approval queues * Let customers keep low-value items instead of shipping them back * Trigger automatic refunds when a return is completed If you do not need special logic yet, you can launch without Flows and add them later. For setup details, trigger types, evaluation order, and example automations, see [Automate Returns with Flows](/labs/returns-flows). ## Step 8: Test the Full Flow Before sharing the portal with customers, run one return end to end: 1. Open your returns portal (`https://your-store.returns.shipbob.app`). 2. Enter a real order number and the email address on the order. 3. Select an item, answer any condition questions, and submit the return. 4. Confirm the return appears on your **Returns** page in the dashboard. 5. If auto-approve is off, approve it and confirm the label email arrives. 6. Check that the return also appears in your ShipBob Merchant Portal as an RMA. If you configured any Flows, also test at least one return that should trigger each important rule. ## Pre-Launch Checklist Before publishing your portal broadly, confirm that: * Shopify is connected successfully * Your ShipBob PAT passes **Test Connection** * Your return routing warehouse is set correctly * Your return policy, return window, and return reasons reflect your actual business rules * Your Flows, if any, fire in the order you expect * Your branding changes appear correctly in the portal * Your sender domain is verified, if you are using one * A real end-to-end test return has completed successfully ## Optional: Customize Customer Emails ShipBob Returns emails your customers at each stage of the return: **Return received**, **Label ready**, **In transit**, and **Completed**. If you want to go beyond the default templates before launch: 1. Open **Settings** and click **Customize** next to any email type. 2. Edit the **subject line**, **message text**, and **closing note**. 3. Use merge fields such as customer name, order number, and tracking link to personalize each message. 4. Click **Send test email** to preview the message in your inbox before going live. ## Step 9: Share Your Returns Portal You are live! Add your returns portal link where customers will look for it: * Your website footer and FAQ / returns policy page * Order confirmation and shipping notification emails * Your Shopify customer account pages ## Ongoing Operations After launch, check the dashboard regularly for: * Returns waiting in **Pending Approval** * SKU matching issues that need an **Auto-sync** rerun * Failed or delayed customer email delivery * Custom-domain or sender-domain verification problems * Any return-policy or flow changes that should be retested before customers use them *** ## Troubleshooting **Products show as "could not be matched to ShipBob inventory"** Make sure the SKUs in Shopify match the SKUs in ShipBob, then click **Auto-sync** in **Settings > Integrations**. **Custom domain will not verify** Confirm the CNAME record matches the value shown on screen exactly and that no conflicting records exist for the same hostname. DNS changes can take up to a few hours to propagate. **Test email did not arrive** Check your spam folder first. If you are using a custom sender domain, make sure all DNS records on the sender domain screen show as verified. **A customer says they can't start a return** Check the return window first. Also confirm the item is not blocked by a non-returnable product tag, an excluded SKU, a hazmat restriction, or an Auto-Reject flow. Need more help? Contact your ShipBob support representative.