Shipping

The Shipping API provides access to multi-carrier shipping quotes, label generation, and tracking. Get rates from FedEx, UPS, DHL, and regional carriers, then create shipments with a single API call.

All endpoints require authentication via Bearer token with shipping:read or shipping:write scope.

POST/v1/shipping/quotes

Get shipping quotes

Get shipping rates from multiple carriers for a package. Optionally include DDP (Delivered Duty Paid) calculations.

Required attributes

Name
origin
Type
object
Description
Origin address with country, postal_code, city, state.
Name
destination
Type
object
Description
Destination address with country, postal_code, city, state.
Name
packages
Type
array
Description
Array of packages with weight, length, width, height.

Optional attributes

Name
declared_value
Type
number
Description
Total declared value for customs.
Name
currency
Type
string
Description
Currency for declared value (default: USD).
Name
carriers
Type
array
Description
Specific carriers to quote: fedex, ups, dhl, usps.
Name
include_ddp
Type
boolean
Description
Include DDP calculations (default: false).

Request

POST

/v1/shipping/quotes

curl -X POST https://app.price2b.com/api/v1/shipping/quotes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {
      "country": "US",
      "postal_code": "33166",
      "city": "Miami",
      "state": "FL"
    },
    "destination": {
      "country": "AR",
      "postal_code": "C1043",
      "city": "Buenos Aires",
      "state": "C"
    },
    "packages": [
      {
        "weight": 2.5,
        "length": 30,
        "width": 20,
        "height": 15,
        "weight_unit": "kg",
        "dimension_unit": "cm"
      }
    ],
    "declared_value": 150.00,
    "currency": "USD",
    "carriers": ["fedex", "ups", "dhl"],
    "include_ddp": true
  }'

Response

{
  "success": true,
  "data": {
    "quote_id": "QT-2026-001234",
    "valid_until": "2026-01-31T23:59:59Z",
    "rates": [
      {
        "carrier": "fedex",
        "service": "INTERNATIONAL_ECONOMY",
        "service_name": "FedEx International Economy",
        "transit_days": 5,
        "delivery_date": "2026-02-05",
        "shipping_cost": {
          "amount": 45.50,
          "currency": "USD"
        },
        "ddp_cost": {
          "amount": 32.15,
          "currency": "USD"
        },
        "total_cost": {
          "amount": 77.65,
          "currency": "USD"
        }
      },
      {
        "carrier": "ups",
        "service": "WORLDWIDE_EXPEDITED",
        "service_name": "UPS Worldwide Expedited",
        "transit_days": 4,
        "delivery_date": "2026-02-04",
        "shipping_cost": {
          "amount": 52.00,
          "currency": "USD"
        },
        "ddp_cost": {
          "amount": 32.15,
          "currency": "USD"
        },
        "total_cost": {
          "amount": 84.15,
          "currency": "USD"
        }
      }
    ]
  }
}

POST/v1/shipping/shipments

Create a shipment

Creates a shipment and purchases a label. You can use a quote ID from a previous quote request, or provide full shipment details.

Required attributes

Name
quote_id
Type
string
Description
Quote ID from a previous quote request.
Name
selected_rate_index
Type
integer
Description
Index of the selected rate from the quote (0-based).
Name
shipper
Type
object
Description
Shipper address (full AddressDTO).
Name
recipient
Type
object
Description
Recipient address (full AddressDTO).

Optional attributes

Name
packages
Type
array
Description
Override package details from quote.
Name
customs_items
Type
array
Description
Customs declaration items for international shipments.
Name
reference
Type
string
Description
Your internal reference (e.g., order number).

Request

POST

/v1/shipping/shipments

curl -X POST https://app.price2b.com/api/v1/shipping/shipments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "QT-2026-001234",
    "selected_rate_index": 0,
    "shipper": {
      "name": "John Doe",
      "company": "Acme Corp",
      "address1": "123 Main St",
      "city": "Miami",
      "state": "FL",
      "postal_code": "33166",
      "country": "US",
      "phone": "+1-305-555-1234",
      "email": "john@acme.com"
    },
    "recipient": {
      "name": "Juan Pérez",
      "address1": "Av. Corrientes 1234",
      "city": "Buenos Aires",
      "state": "C",
      "postal_code": "C1043",
      "country": "AR",
      "phone": "+54-11-4000-0000",
      "email": "juan@example.com",
      "tax_id": "20-12345678-9"
    },
    "customs_items": [
      {
        "description": "Wireless Headphones",
        "quantity": 2,
        "unit_value": 49.99,
        "currency": "USD",
        "weight": 0.25,
        "hs_code": "8518300000",
        "country_of_origin": "CN"
      }
    ],
    "reference": "ORDER-2026-001"
  }'

Response (201)

{
  "success": true,
  "message": "Shipment created successfully",
  "data": {
    "shipment_id": 12345,
    "carrier": "fedex",
    "service": "INTERNATIONAL_ECONOMY",
    "tracking_number": "794644790303",
    "status": "label_created",
    "label_url": "https://app.price2b.com/api/v1/shipping/shipments/12345/label",
    "charges": {
      "shipping": 45.50,
      "ddp": 32.15,
      "total": 77.65,
      "currency": "USD"
    },
    "estimated_delivery": "2026-02-05"
  }
}

GET/v1/shipping/shipments

List shipments

Returns a paginated list of shipments.

Query parameters

Name
page
Type
integer
Description
Page number (default: 1).
Name
per_page
Type
integer
Description
Items per page (default: 20, max: 100).
Name
status
Type
string
Description
Filter by status: label_created, in_transit, delivered, cancelled.
Name
carrier
Type
string
Description
Filter by carrier.
Name
date_from
Type
datetime
Description
Shipments created after this date.
Name
date_to
Type
datetime
Description
Shipments created before this date.

Request

GET

/v1/shipping/shipments

curl -G https://app.price2b.com/api/v1/shipping/shipments \
  -H "Authorization: Bearer {token}" \
  -d status=in_transit \
  -d per_page=20

Response

{
  "success": true,
  "data": {
    "shipments": [
      {
        "id": 12345,
        "carrier": "fedex",
        "tracking_number": "794644790303",
        "status": "in_transit",
        "reference": "ORDER-2026-001",
        "created_at": "2026-01-30T10:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 45
    }
  }
}

GET/v1/shipping/shipments/:id

Get shipment details

Retrieves full details for a shipment including tracking events.

Request

GET

/v1/shipping/shipments/12345

curl https://app.price2b.com/api/v1/shipping/shipments/12345 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": 12345,
    "carrier": "fedex",
    "service": "INTERNATIONAL_ECONOMY",
    "tracking_number": "794644790303",
    "status": "in_transit",
    "shipper": {"..."},
    "recipient": {"..."},
    "packages": ["..."],
    "charges": {
      "shipping": 45.50,
      "ddp": 32.15,
      "total": 77.65
    },
    "tracking_events": [
      {
        "timestamp": "2026-01-31T08:00:00Z",
        "status": "in_transit",
        "description": "In transit to destination",
        "location": "Memphis, TN"
      },
      {
        "timestamp": "2026-01-30T14:00:00Z",
        "status": "picked_up",
        "description": "Picked up",
        "location": "Miami, FL"
      }
    ],
    "created_at": "2026-01-30T10:00:00Z"
  }
}

GET/v1/shipping/shipments/:id/label

Download label

Downloads the shipping label as a PDF file.

Query parameters

Name
format
Type
string
Description
Label format: pdf (default), png, zpl.

Request

GET

/v1/shipping/shipments/12345/label

curl https://app.price2b.com/api/v1/shipping/shipments/12345/label \
  -H "Authorization: Bearer {token}" \
  -o label.pdf

Returns binary PDF content with Content-Type: application/pdf.

POST/v1/shipping/shipments/:id/cancel

Cancel a shipment

Cancels a shipment and voids the label. Only available for shipments that haven't been picked up.

Request

POST

/v1/shipping/shipments/12345/cancel

curl -X POST https://app.price2b.com/api/v1/shipping/shipments/12345/cancel \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Shipment cancelled successfully",
  "data": {
    "shipment_id": 12345,
    "status": "cancelled",
    "refund_amount": 45.50,
    "refund_currency": "USD"
  }
}

GET/v1/shipping/shipments/:id/tracking

Get tracking

Gets the latest tracking events for a shipment.

Request

GET

/v1/shipping/shipments/12345/tracking

curl https://app.price2b.com/api/v1/shipping/shipments/12345/tracking \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "tracking_number": "794644790303",
    "carrier": "fedex",
    "status": "in_transit",
    "estimated_delivery": "2026-02-05",
    "events": [
      {
        "timestamp": "2026-01-31T16:00:00Z",
        "status": "in_transit",
        "description": "Departed FedEx hub",
        "location": "Miami, FL"
      },
      {
        "timestamp": "2026-01-31T08:00:00Z",
        "status": "in_transit",
        "description": "Arrived at FedEx hub",
        "location": "Miami, FL"
      }
    ]
  }
}

POST/v1/shipping/shipments/tracking/batch

Batch tracking

Get tracking information for multiple shipments at once.

Required attributes

Name
tracking_numbers
Type
array
Description
Array of tracking numbers (max: 50).

Request

POST

/v1/shipping/shipments/tracking/batch

curl -X POST https://app.price2b.com/api/v1/shipping/shipments/tracking/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_numbers": [
      "794644790303",
      "1Z999AA10123456784",
      "5432187654"
    ]
  }'

Response

{
  "success": true,
  "data": {
    "tracking": [
      {
        "tracking_number": "794644790303",
        "carrier": "fedex",
        "status": "delivered",
        "delivered_at": "2026-02-05T14:30:00Z"
      },
      {
        "tracking_number": "1Z999AA10123456784",
        "carrier": "ups",
        "status": "in_transit",
        "estimated_delivery": "2026-02-06"
      }
    ]
  }
}

GET/v1/shipping/carrier-accounts

List carrier accounts

Lists your registered carrier accounts.

Request

GET

/v1/shipping/carrier-accounts

curl https://app.price2b.com/api/v1/shipping/carrier-accounts \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": 1,
        "carrier": "fedex",
        "account_number": "****5678",
        "nickname": "Main FedEx Account",
        "is_default": true,
        "created_at": "2025-06-15T10:00:00Z"
      },
      {
        "id": 2,
        "carrier": "ups",
        "account_number": "****1234",
        "nickname": "UPS Business",
        "is_default": false,
        "created_at": "2025-08-20T14:00:00Z"
      }
    ]
  }
}