- International Shipping
- Commercial Invoice Requirements
International Shipping
Commercial Invoice Requirements
Required fields and data for international shipping compliance
Applicability: This section is only required if you plan to ship internationally with MasonHub.
For international orders, MasonHub relies on your API payload to create compliant commercial invoices that meet customs requirements. Proper commercial invoice data is essential for smooth international shipping and customs clearance.
Overview
Commercial invoices are legal documents required for international shipments that provide customs authorities with details about the goods being shipped, their value, and origin.
Compliance Critical: Incorrect or missing commercial invoice data can result in shipment delays, additional fees, or customs holds.
Required Order-Level Fields
When creating international orders, include these mandatory fields in your API payload:
Currency and Pricing Fields
| Field | Type | Description | Example |
|---|---|---|---|
currency_code | String | Currency of the transaction (ISO 4217) | "USD", "EUR", "CAD" |
total_line_items_price | Decimal | Total price before any discounts | 150.00 |
total_discounts | Decimal | Total line-level discounts applied | 15.00 |
total_price | Decimal | Net total (line items - discounts) | 135.00 |
Calculation Formula
total_price = total_line_items_price - total_discounts
MasonHub automatically allocates discounts across multiple shipments proportionally when orders split into multiple packages.
Required Line Item Fields
Each line item in international orders must include:
Pricing Information
| Field | Type | Description | Example |
|---|---|---|---|
price | Decimal | Unit price per item (not extended total) | 40.00 for 2×$40 items |
Important: The price field should be the unit price, not the extended total. For example, if you’re shipping 2 items at $40 each, the price should be 40.00, not 80.00.
Example International Order Payload
{
"order": {
"external_id": "INTL-ORDER-12345",
"currency_code": "USD",
"total_line_items_price": 185.00,
"total_discounts": 15.00,
"total_price": 170.00,
"shipping_address": {
"name": "Jean Dupont",
"street": "123 Rue de la Paix",
"city": "Paris",
"state": "Île-de-France",
"zip": "75001",
"country": "FR"
},
"line_items": [
{
"sku": "PRODUCT-001",
"quantity": 2,
"price": 50.00,
"name": "Premium Widget",
"description": "High-quality widget for industrial use"
},
{
"sku": "PRODUCT-002",
"quantity": 1,
"price": 85.00,
"name": "Professional Gadget",
"description": "Professional-grade electronic gadget"
}
]
}
}
Additional International Considerations
Product Information
Ensure your SKUs include international-specific data:
Restricted Items
Verify that products can be legally shipped to the destination country. Some items may be restricted or prohibited.
Common restrictions include:
- Electronics with certain frequencies
- Food and agricultural products
- Pharmaceuticals and medical devices
- Weapons and military equipment
- Cultural artifacts
Currency Considerations
Supported Currencies
MasonHub supports major international currencies. Common options include:
North America
- USD (US Dollar)
- CAD (Canadian Dollar)
- MXN (Mexican Peso)
Europe
- EUR (Euro)
- GBP (British Pound)
- CHF (Swiss Franc)
Asia Pacific
- JPY (Japanese Yen)
- AUD (Australian Dollar)
- SGD (Singapore Dollar)
Exchange Rate Handling
- Use the currency the customer was charged in
- Ensure consistency across all monetary fields
- Consider exchange rate fluctuations for multi-day processing
Customs Documentation
Commercial Invoice Content
The commercial invoice generated by MasonHub will include:
Shipper Information
MasonHub warehouse details and contact information
Consignee Information
Customer shipping address and contact details
Product Details
SKU descriptions, quantities, unit values, and total values
Totals and Currency
Line item totals, discounts, and final invoice amount
Additional Documents
Depending on the destination and products, additional documentation may be required:
- Certificate of Origin: For preferential duty rates
- Export Licenses: For controlled goods
- Product Certifications: For regulated products
- Insurance Documentation: For high-value shipments
Compliance Best Practices
Data Accuracy
Product Descriptions
- Use specific, detailed descriptions
- Include material composition
- Avoid marketing language
- Be consistent with harmonized codes
Values and Pricing
- Use actual transaction values
- Include all fees and charges
- Be consistent with payment records
- Round appropriately for currency
Record Keeping
Maintain records of:
- Original order values and currency
- Exchange rates used
- Discount calculations
- Product classifications
- Shipping documentation
Testing International Orders
Sandbox Testing
Create Test International SKUs
Include harmonized codes and origin countries
Submit Test Orders
Use various international addresses and currencies
Verify Invoice Generation
Review generated commercial invoices for accuracy
Test Edge Cases
Multiple currencies, split shipments, returns
Common Issues & Solutions
API Reference
Create Order API Documentation
Complete API documentation with international order examples
Support for International Shipping
For questions about international shipping requirements or commercial invoice setup:
Integration Support
Technical API and integration questions
Operations Support
International shipping and compliance questions
Email: support@masonhub.co
Next Steps
After configuring international order support, proceed to production readiness to prepare for launch.