Shippo Integration Documentation

Thanks for visiting my GitHub account!

Overview

This document describes the complete Shippo integration implemented for Sustainable Trades.

The purpose of this documentation is to provide a complete reference for current and future developers so the integration can be maintained, extended, and deployed without confusion.

This integration uses Shippo's Partner OAuth (Grey Label) flow combined with Shippo Order Sync APIs.

---

Table of Contents

1. Introduction
2. Integration Architecture
3. Shippo Partner Account Setup
4. Shippo Credentials Setup
5. Environment Configuration
6. Database Structure
7. OAuth Authentication Flow
8. API Endpoints
9. Carrier Account Synchronization
10. Shipping Rate Preferences
11. Order Synchronization
12. Webhook Integration
13. Tracking Lifecycle
14. Postman Testing Guide
15. Common Issues
16. Production Deployment Checklist
17. Future Enhancements

---

1. Introduction

What is Shippo?

Shippo is a shipping platform that provides:

• Shipping label creation
• Carrier account management
• Shipping rate comparison
• Package tracking
• Shipment notifications
• Return label support

Official Website:

https://goshippo.com

Official Documentation:

https://docs.goshippo.com

---

2. Integration Architecture

Sustainable Trades uses a Hybrid Integration Strategy.

Part 1: OAuth Integration

Users connect their own Shippo account through Sustainable Trades.

Benefits:

• Users manage their own Shippo account.
• Users manage their own Shippo billing.
• Sustainable Trades does not handle shipping invoices.
• Sustainable Trades acts on behalf of connected users.

---

Part 2: Order Synchronization

Orders are created inside Sustainable Trades and synchronized to Shippo.

Flow:

Customer Creates Order ↓ Order Stored In Sustainable Trades ↓ Order Synced To Shippo ↓ Vendor Uses Shippo Dashboard ↓ Label Created ↓ Tracking Generated ↓ Tracking Updates Returned Through Webhooks

---

3. Shippo Partner Account Setup

Step 1: Create Shippo Account

Create an account at:

https://portal.goshippo.com

After registration, verify your email address.

---

Step 2: Contact Shippo

Partner OAuth credentials are not available automatically.

Contact Shippo:

Technical Support:

solutions@shippo.com

General Support:

support@shippo.com

Example Request:

Subject: OAuth Partner Integration Request

Hello Shippo Team,

We would like to integrate Shippo OAuth into our platform using the Grey Label Integration approach.

Please provide:

• Client ID
• Client Secret
• Redirect URL Registration Instructions

Thank you.

---

Step 3: Receive Credentials

Shippo will provide:

Client ID

6e67e42c6aad40308f2a3e5357eaa110

Client Secret

****************************

Example only.

Never commit credentials to Git.

---

Step 4: Register Redirect URL

Provide Shippo with your callback URL.

Example:

https://api.sustainabletrades.com/shippo/oauth/callback

Shippo must whitelist this URL.

OAuth will fail if the callback URL is not registered.

---

4. Shippo Credentials Setup

Add credentials to environment variables.

SHIPPO_CLIENT_ID=
SHIPPO_CLIENT_SECRET=
SHIPPO_REDIRECT_URL=
SHIPPO_FRONTEND_REDIRECT_URL=

Example:

SHIPPO_CLIENT_ID=xxxxxxxxxxxxxxxx
SHIPPO_CLIENT_SECRET=xxxxxxxxxxxxxxxx
SHIPPO_REDIRECT_URL=https://api.example.com/shippo/oauth/callback
SHIPPO_FRONTEND_REDIRECT_URL=https://app.example.com/settings/shipping

---

5. Laravel Configuration

config/services.php

'shippo' => [
    'client_id'     => env('SHIPPO_CLIENT_ID'),
    'client_secret' => env('SHIPPO_CLIENT_SECRET'),
    'redirect_url'  => env('SHIPPO_REDIRECT_URL'),
]

---

6. Database Structure

shop_infos

Stores Shippo connection information.

Column	Description
shippo_access_token	OAuth access token
shippo_connected	Connection status
shippo_connected_at	Connection timestamp
carriers_accounts_synced_at	Last sync timestamp

---

shippo_carrier_accounts

Stores vendor carrier accounts.

Column	Description
shop_info_id	Shop reference
carrier	usps, ups, fedex
carrier_name	Display name
shippo_object_id	Shippo carrier account ID
active	Enabled status

---

shippo_rate_preferences

Stores vendor shipping preferences.

Column	Description
shop_info_id	Shop reference
rate_type	cheapest / fastest
active	Status

---

orders

Additional Shippo fields.

Column	Description
shippo_order_id	Shippo order ID
tracking_number	Tracking number
carrier	Carrier name
shipping_status	Tracking status
delivered_at	Delivery timestamp

---

7. OAuth Authentication Flow

Step 1

Frontend calls:

POST /shippo/connect

Response:

{
  "success": true,
  "data": {
    "url": "https://goshippo.com/oauth/authorize?..."
  }
}

---

Step 2

User is redirected to:

https://goshippo.com/oauth/authorize

User signs in or creates Shippo account.

---

Step 3

Shippo redirects:

GET /shippo/oauth/callback

Example:

https://api.example.com/shippo/oauth/callback?code=AUTH_CODE&state=ENCRYPTED_USER

---

Step 4

Exchange Authorization Code.

Request:

POST https://goshippo.com/oauth/access_token

Payload:

{
  "grant_type": "authorization_code",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "code": "AUTH_CODE"
}

---

Step 5

Response:

{
  "access_token": "oauth.xxxxxxxxx",
  "token_type": "Bearer",
  "scope": "*"
}

---

Step 6

Store access token securely.

encrypt($accessToken)

---

Step 7

Automatically:

• Sync carriers
• Create shipping preferences
• Redirect user back to frontend

---

8. Available API Endpoints

Connect Shippo

POST /shippo/connect

---

Disconnect Shippo

POST /shippo/disconnect

---

Get Access Token

GET /shippo/access-token

Development use only.

Should be removed or restricted in production.

---

Sync Carrier Accounts

POST /shippo/sync-carriers-accounts/{user}

---

Get Carriers

GET /shippo/carriers

---

Update Carrier Status

POST /shippo/carrier/{carrierAccount}

Request:

{
  "active": true
}

---

Get Rate Preferences

GET /shippo/rate-preferences

---

Update Rate Preference

POST /shippo/rate-preference/{ratePreference}

Request:

{
  "active": true
}

---

9. Carrier Account Synchronization

Shippo API:

GET https://api.goshippo.com/carrier_accounts/

Authorization:

Bearer ACCESS_TOKEN

---

Supported Carriers:

• USPS
• UPS
• FedEx

The system guarantees all three records exist locally.

Example:

Carrier	Active	Shippo Object ID
USPS	false	null
UPS	true	e14621fc896
FedEx	false	null

---

10. Shipping Rate Preferences

Supported options:

• Cheapest
• Fastest

Default creation:

Cheapest = Active
Fastest = Inactive

Business Rule:

Only one rate preference can be active at a time.

When one is activated, all others are automatically deactivated.

---

11. Order Synchronization

Purpose:

Push Sustainable Trades orders into Shippo.

Shippo Endpoint:

POST https://api.goshippo.com/orders/

Authorization:

Bearer ACCESS_TOKEN

---

Example Payload

{
  "order_number": "ORD123456",
  "order_status": "PAID",
  "currency": "USD",
  "subtotal_price": "100.00",
  "total_price": "110.00",
  "metadata": {
    "local_order_id": 100
  }
}

---

Example Response

{
  "object_id": "abcdef123456"
}

Store:

shippo_order_id

inside orders table.

---

12. Webhook Integration

Webhook Route

POST /webhooks/shippo

Current Events:

• transaction_created
• transaction_updated
• track_updated

---

transaction_created

Purpose:

Capture tracking number after label purchase.

Stores:

tracking_number
carrier

---

track_updated

Purpose:

Update shipping status.

Supported Status Mapping:

Shippo	Local
PRE_TRANSIT	label_created
TRANSIT	in_transit
OUT_FOR_DELIVERY	out_for_delivery
DELIVERED	delivered
RETURNED	returned
FAILURE	failed

---

13. Tracking Lifecycle

Order Created ↓ Order Synced To Shippo ↓ Vendor Creates Label In Shippo ↓ Transaction Created ↓ Tracking Number Generated ↓ Webhook Received ↓ Tracking Number Stored ↓ Package Moves Through Carrier Network ↓ Tracking Updates Received ↓ Delivered

---

14. Postman Testing Guide

Test Carrier Accounts

GET https://api.goshippo.com/carrier_accounts/

Headers:

Authorization: Bearer ACCESS_TOKEN

---

Test Order Creation

POST https://api.goshippo.com/orders/

Headers:

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

---

Test OAuth

1. Call connect endpoint.
2. Open returned URL.
3. Complete Shippo authorization.
4. Capture callback code.
5. Verify token storage.
6. Verify carrier sync.

---

15. Common Issues

OAuth Redirect Error

Cause:

Redirect URL not registered with Shippo.

Solution:

Ask Shippo support to whitelist callback URL.

---

Invalid Access Token

Cause:

Expired or revoked authorization.

Solution:

Reconnect Shippo account.

---

Carrier Sync Returns Empty

Cause:

No carriers configured in Shippo.

Solution:

Configure carrier accounts in Shippo dashboard.

---

Order Sync Failure

Cause:

Missing required order data.

Solution:

Verify payload structure matches Shippo documentation.

---

16. Production Deployment Checklist

• Shippo Partner Account Approved
• Client ID Received
• Client Secret Received
• Redirect URL Registered
• Webhook URL Configured
• SSL Enabled
• Environment Variables Configured
• Token Encryption Verified
• Carrier Sync Tested
• Order Sync Tested
• Tracking Updates Tested
• Delivery Updates Tested

---

17. Future Enhancements

The following features are not yet implemented:

• Shipment Creation API
• Label Purchase API
• Shipping Rate Retrieval API
• Automated Tracking Registration
• Return Labels
• Delivery Notifications
• Shipment Insurance
• In-App Shipping Dashboard

---

Maintainers

Project: Sustainable Trades Integration Type: Shippo OAuth + Order Sync Integration Backend Framework: Laravel Last Updated: June 2026

---

Author

Developed and maintained by MD. Rahatul Rabbi.

Follow

---

#learnwithfair #rahtulrabbi #rahatul-rabbi #learn-with-fair