How to connect with Shipway

Shipway API Authentication

The Shipway API uses Basic HTTP authentication with your email and license key.

• Username: Your Shipway Email
• Password: Your License Key
• You can find your License Key from: Shipway → Profile → Manage profile

Authorization Header Construction

The Authorization header is constructed as follows:

• 1. Username (Email) and Password (License Key) are combined into a string "username:password"
• 2. The resulting string is then encoded in base64
• PHP example:
• $token = base64_encode("email:License key");
• $authHeaderString = 'Authorization: Basic ' . $token;

⚠️ Important Security Notes

⚠️ Once you generate a new Token, your old token will stop working immediately

• ⏰ Once you generate your token, it will be visible for 5 minutes and then will be hidden from view
• 🔒 To protect your data, you'll only be able to reveal your API token once
• 💾 Copy and save your API token in a secure place

How can I test Shipway APIs?

You can test and read API documentation:

• Read API documentation by logging in to Shipway
• Please refer to this article on Client Developer Portal

Connect Shipway to Returndotai

Once you have your API Key, connect it to your Returndotai account.

1. 1Log in to your Returndotai Returns dashboard
2. 2Navigate to the "Settings" section in the left menu
3. 3Click on "Logistics" tab
4. 4Look for the Shipway integration option
5. 5Click "Connect" or "Set up" button
6. 6You'll be prompted to enter your API Key
7. 7Paste the License Key you received into the field
8. 8Click "Connect" to establish the connection

Verify Connection

After clicking Connect, the system will validate your API credentials and confirm the connection is successful.

• Green checkmark indicates successful connection
• You'll see "Connected" status next to Shipway
• Your account is now ready to generate shipping labels

Configure Package Settings

Set up your default shipping preferences after connecting.

1. 1Set your default package sizes (Small, Medium, Large)
2. 2Set default package types (Box, Envelope, Poly mailer)
3. 3Configure weight settings for automatic calculations

Enable "Ship with Pre-paid Label" Method

Make sure the prepaid label method is enabled for customers.

1. 1In the Settings section, locate Return Methods
2. 2Find "Ship with pre-paid label" option
3. 3Toggle it to ENABLED
4. 4This method will now be displayed on the customer return page
5. 5Customers can select this option when submitting returns

⚠️ Important Configuration Note

The "Ship with pre-paid label" method is only displayed on the return page if you enable it in the app

• Customers will not see this option if it's disabled
• Make sure to enable it before testing

Create a Test Return Request

Test the integration before going live with customers.

1. 1Go to your store's return page (customer-facing)
2. 2Create a test return request
3. 3 • Enter email and order number
4. 4 • Select items to return
5. 5 • Choose return reasons
6. 6For return method, select "Ship with pre-paid label"
7. 7 • This option should now be visible
8. 8Complete and submit the return request
9. 9Note the RMA number generated

Approve Request & Generate Label

Process the test return in your dashboard.

1. 1Log in to the Returndotai app/dashboard
2. 2Navigate to "Return Management" tab
3. 3Find the test return request you just created
4. 4Click on the request to open details
5. 5Click "Approve" button to approve the request
6. 6Select the appropriate shipping carrier if prompted
7. 7 • Choose Shipway as the carrier
8. 8 • Select package size
9. 9System will generate the prepaid label automatically
10. 10Label generation may take a few seconds

Verify Label Information

Check that the generated label is correct.

1. 1After label generation, click "View Label" or "Download Label"
2. 2Verify the following information is accurate:
3. 3 • Sender address (your return/warehouse address)
4. 4 • Recipient address (customer address)
5. 5 • Package details (weight, dimensions)
6. 6 • Tracking number is present
7. 7 • Barcode is readable
8. 8 • Return instructions are clear
9. 9Print or download the label for testing
10. 10If everything looks correct, your integration is working!

Test Tracking (Optional)

Verify that tracking updates work correctly:

• Note the tracking number from the label
• Check tracking status in Shipway dashboard
• Verify tracking updates appear in Returndotai dashboard
• Confirm customer receives tracking notification email

API Key Security

Never share your License Key publicly or commit it to version control

• Store your API credentials in a secure password manager
• Regenerate your token if you suspect it has been compromised
• Only grant API access to trusted team members
• Use environment variables to store credentials in your systems

Operational Best Practices

Test the integration thoroughly before enabling for customers

• Create test returns with different package sizes to verify settings
• Monitor label generation for the first few days after going live
• Set up automated alerts for failed label generations
• Keep your return/warehouse address updated in Shipway
• Review shipping costs regularly to ensure accuracy

Customer Experience Tips

Enable "Ship with pre-paid label" only after successful testing

• Provide clear instructions on how to use the prepaid label
• Include label printing instructions in confirmation emails
• Offer alternative return methods for customers without printers
• Set customer expectations on label delivery time (email)
• Monitor customer feedback on the label quality and usability

Common Issues and Solutions

Key points to understand:

• Issue: Connection failed when entering API Key
• → Solution: Verify you're using the License Key (not password). Copy it exactly from Shipway → Profile → Manage profile.
• Issue: "Ship with pre-paid label" not showing on return page
• → Solution: Enable the method in Settings → Return Methods. Toggle "Ship with pre-paid label" to ON.
• Issue: Label generation fails with error
• → Solution: Check that your Shipway account has sufficient credit. Verify return address is configured correctly in Shipway.
• Issue: Old API token stopped working
• → Solution: This is expected - generating a new token invalidates the old one. Use the new token in Returndotai settings.
• Issue: Can't see API token after 5 minutes
• → Solution: Token is hidden for security. If you didn't copy it, generate a new token in Shipway.
• Issue: Label has incorrect address
• → Solution: Update your warehouse/return address in Shipway settings. Test with a new return request.
• Issue: Tracking number not updating
• → Solution: Wait 24 hours for first update. Check Shipway dashboard to verify shipment was created correctly.

Getting Support

If you encounter issues not covered above:

• For Shipway API issues: Contact Shipway support at support@shipway.in
• For Returndotai integration issues: Contact our support via live chat or email support@returndotai.com
• Provide: Your Shipway account email, error messages, and screenshots of the issue
• Reference this documentation article when contacting support