Shipping Costs Guide

This guide explains how to calculate shipping costs for outbound orders using the Spreetail Channel Integration API.

Overview

The shipping cost calculation endpoint allows you to:

Get accurate shipping cost estimates
Compare different shipping options
Calculate costs before order creation
Optimize shipping decisions

ℹ️
Note: The shipping cost endpoint requires enablement. Contact [email protected] to enable this feature for your account.

Endpoint

POST /outbound-cost

Full URL: https://api.spreetaileu.com/api/api/v1/outbound-cost

Authentication

Requires Bearer token authentication. See the Authentication Guide for details.

Request Structure

To calculate shipping costs, provide:

Delivery Address: Destination address
Order Items: Products with weights/dimensions (if applicable)
Shipping Options: Preferred carriers or services (optional)

Required Fields

Field	Type	Description
`DeliveryAddress`	object	Complete delivery address
`OrderItems`	array	Items in the order

Example Request

{
  "DeliveryAddress": {
    "FullName": "John Doe",
    "Address1": "123 Main Street",
    "Town": "Berlin",
    "PostCode": "10115",
    "Country": "Germany",
    "CountryCode": "DE"
  },
  "OrderItems": [
    {
      "SKU": "PROD-12345",
      "Qty": 2,
      "Weight": 0.5,
      "Dimensions": {
        "Length": 20,
        "Width": 15,
        "Height": 10
      }
    }
  ],
  "Currency": "EUR"
}

Code Examples

Python

import requests

def calculate_shipping_cost(access_token, cost_data):
    """Calculate shipping cost for an order"""
    url = "https://api.spreetaileu.com/api/api/v1/outbound-cost"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, headers=headers, json=cost_data)
    response.raise_for_status()
    return response.json()

# Example usage
cost_request = {
    "DeliveryAddress": {
        "FullName": "John Doe",
        "Address1": "123 Main Street",
        "Town": "Berlin",
        "PostCode": "10115",
        "Country": "Germany",
        "CountryCode": "DE"
    },
    "OrderItems": [{
        "SKU": "PROD-12345",
        "Qty": 2,
        "Weight": 0.5
    }],
    "Currency": "EUR"
}

result = calculate_shipping_cost(access_token, cost_request)
print(f"Shipping cost: {result['data']['cost']} {result['data']['currency']}")

JavaScript/Node.js

async function calculateShippingCost(accessToken, costData) {
  const url = 'https://api.spreetaileu.com/api/api/v1/outbound-cost';
  
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(costData)
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Shipping cost calculation failed: ${error.error || response.statusText}`);
  }
  
  return await response.json();
}

// Example usage
const costRequest = {
  DeliveryAddress: {
    FullName: 'John Doe',
    Address1: '123 Main Street',
    Town: 'Berlin',
    PostCode: '10115',
    Country: 'Germany',
    CountryCode: 'DE'
  },
  OrderItems: [{
    SKU: 'PROD-12345',
    Qty: 2,
    Weight: 0.5
  }],
  Currency: 'EUR'
};

calculateShippingCost(accessToken, costRequest)
  .then(result => {
    console.log(`Shipping cost: ${result.data.cost} ${result.data.currency}`);
  })
  .catch(error => console.error('Error:', error));

Response Format

Success Response (200)

{
  "success": true,
  "data": {
    "cost": 5.99,
    "currency": "EUR",
    "estimated_delivery_days": 3,
    "carrier": "DHL",
    "service": "Standard",
    "breakdown": {
      "base_cost": 4.99,
      "surcharges": 1.00,
      "tax": 0.00
    }
  }
}

Response Fields

Field	Type	Description
`cost`	number	Total shipping cost
`currency`	string	Currency code
`estimated_delivery_days`	integer	Estimated delivery time in days
`carrier`	string	Shipping carrier name
`service`	string	Service level
`breakdown`	object	Cost breakdown details

Use Cases

1. Pre-order Cost Calculation

def get_order_total_with_shipping(access_token, order_data):
    """Calculate total order cost including shipping"""
    # Calculate shipping
    shipping_cost = calculate_shipping_cost(access_token, {
        "DeliveryAddress": order_data["DeliveryAddress"],
        "OrderItems": order_data["OrderItems"],
        "Currency": order_data["Currency"]
    })
    
    # Calculate item total
    item_total = sum(
        item["Qty"] * item["PricePerUnit"] 
        for item in order_data["OrderItems"]
    )
    
    # Total with shipping
    total = item_total + shipping_cost["data"]["cost"]
    
    return {
        "item_total": item_total,
        "shipping_cost": shipping_cost["data"]["cost"],
        "total": total,
        "currency": order_data["Currency"]
    }

2. Compare Shipping Options

def compare_shipping_options(access_token, address, items):
    """Compare different shipping options"""
    base_request = {
        "DeliveryAddress": address,
        "OrderItems": items,
        "Currency": "EUR"
    }
    
    # Get standard shipping
    standard = calculate_shipping_cost(access_token, {
        **base_request,
        "Service": "Standard"
    })
    
    # Get express shipping
    express = calculate_shipping_cost(access_token, {
        **base_request,
        "Service": "Express"
    })
    
    return {
        "standard": standard["data"],
        "express": express["data"]
    }

Important Notes

Endpoint Enablement

This endpoint requires special enablement
Contact [email protected] to enable
Not all accounts have access by default

Address Requirements

The delivery address must include:

FullName
Address1
Town
PostCode
Country or CountryCode

Weight and Dimensions

Providing weight and dimensions improves accuracy
If not provided, default values may be used
Dimensions should be in centimeters
Weight should be in kilograms

Currency

Specify currency for cost calculation
Supported: EUR, GBP, USD
Costs are returned in the specified currency

Best Practices

Calculate Before Order Creation: Get shipping costs before finalizing orders
Cache Results: Cache shipping costs for similar addresses/items
Handle Errors: Implement fallback for when endpoint is unavailable
Validate Addresses: Ensure addresses are complete and valid
Consider Delivery Time: Factor in estimated delivery days

Error Handling

Endpoint Not Enabled

If the endpoint is not enabled for your account:

{
  "success": false,
  "error": "Shipping cost calculation is not enabled for this account"
}

Solution: Contact [email protected] to enable the feature.

Invalid Address

{
  "success": false,
  "error": "Invalid delivery address"
}

Solution: Verify address format and completeness.

Related Endpoints

POST /outbound - Create order (use shipping cost in order)
GET /order/{order_id} - Check order status and actual shipping cost