Shipment Lifecycle

This guide walks through the full lifecycle of a shipment, from API submission through fee calculation, consignee notification, payment collection, and status relay.

1. Shipment creation

You submit a shipment via POST /api/shipments/ with item details, addresses, and consignee contact information. The API authenticates your request using the X-API-Key header and resolves the brand from the key or the brand_id field.

curl -X POST https://api.dutypro.exelot.com/api/shipments/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dp_live_YOUR_KEY_HERE" \
  -d '{
    "brand_id": "my-brand",
    "currency": "USD",
    "items": [
      {
        "description": "Leather handbag",
        "hs_code": "4202.21",
        "declared_value": 150.00,
        "country_of_origin": "CN",
        "quantity": 1,
        "shipping_cost": 12.50
      }
    ],
    "consignee": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "sender": {
      "name": "Acme Corp",
      "city": "London",
      "zip": "SW1A 2AA",
      "country": "GB"
    }
  }'

The sender and consignee objects carry the origin and destination details for the shipment. See the API Reference for the full field list.

Every item must include both a description and an hs_code. Duty Pro uses the HS code to look up the destination tariff and the description to validate and refine the classification (for example, into the correct import variant for the destination country).

If you don’t provide a reference, Duty Pro generates one automatically. References must be unique per brand within your account.

2. Fee calculation

When a shipment is created, the following happens synchronously:

HS code resolution: Duty Pro resolves the supplied hs_code into destination-specific import and export variants for the specific origin and destination countries, using the description to disambiguate when the code maps to multiple tariff lines.
Pre-customs fee adjustment: any pre-customs fees configured for the brand are distributed pro-rata across items (weighted by each item’s share of the total declared value) before duty calculation. These fees are folded into the cost basis so they affect the duties and taxes calculated. They are not displayed as separate line items to the consignee.

If an item carries a shipping_cost, it is also added to that item’s customs base by the tariff engine. Pre-customs fees and per-item shipping_cost are additive: brand-level pre-customs fees are static per brand, while shipping_cost is dynamic per shipment.
Duty and tax calculation: Duty Pro queries Exelot’s tariff database using the resolved HS codes and adjusted item values. The result includes per-item duty and tax amounts.
Additional fee application: constant and percentage-based fees are applied on top of duties and taxes, subject to their conditions (duty-conditional, country scope). See Fee Configuration for details.
Currency conversion: all amounts are converted to the shipment’s target currency using Exelot-managed exchange rates.

The response includes the full breakdown:

Field	Description
`total_duties`	Sum of duty amounts across all items
`total_taxes`	Sum of tax amounts across all items
`total_additional_country_charges`	Destination-country surcharges imposed in addition to duties and taxes (e.g., fixed processing or environmental charges)
`total_additional_fees`	Sum of all additional fees configured for the brand
`total_amount`	Grand total: duties + taxes + additional country charges + additional fees

3. Payment deadline

If the total amount is greater than zero, Duty Pro calculates a payment deadline based on the brand’s configuration:

Payment expiration days: the number of days the consignee has to pay (default: 5).
Day type: either WORKING (skips weekends and public holidays in the destination country) or CALENDAR (counts all days).

The payment link expires after the deadline.

4. Communications

After shipment creation, Duty Pro schedules notifications to the consignee if the brand has the channel enabled and the contact information is available:

Email: sent promptly after shipment creation. The email includes the brand name, fee summary, and a payment link.
SMS: scheduled for the next daytime window in the consignee’s timezone (derived from the destination country). Contains a shortened payment link.

Communications are only sent if the total amount is greater than zero.

See the Communications guide for details on branding, opt-outs, and delivery tracking.

5. Dashboard visibility

The shipment appears in the dashboard immediately after creation. From the shipment detail view, you can see:

Item details with original and resolved HS codes
Full fee breakdown (duties, taxes, additional fees)
Communication history (email/SMS status and timestamps)
Payment status and payment details
Status relay log (webhook/SFTP delivery history)

6. Payment collection

The consignee opens the payment link and lands on the branded payment page at pay.dutypro.exelot.com. The page displays:

The brand’s visual identity (name, logo, colors)
A line-by-line fee breakdown (only fees marked as visible)
A secure payment form

When the consignee completes payment, the shipment’s payment status is updated to PAID.

See the Payment Page guide for details.

7. Status relay

Duty Pro posts status updates to your systems via the method you configured (webhook or SFTP). Each delivery includes the event that triggered it, for example:

shipment_created: fired when a new shipment is created
payment_completed: fired when the consignee completes payment

The full list of available events is shown in the dashboard under Settings > Status Relay. From that screen you can choose which events should be relayed; unchecked events are skipped.

See the Webhooks and SFTP Relay guides for integration details.

Payment statuses

A shipment’s payment_status progresses through the following states:

Status	Description
`PENDING`	Shipment created, awaiting payment
`PAID`	Payment received
`FAILED`	Payment attempt failed
`EXPIRED`	Payment deadline passed without payment