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",
        "declared_value": 150.00,
        "currency": "USD",
        "country_of_origin": "CN",
        "quantity": 1
      }
    ],
    "consignee_name": "Jane Smith",
    "consignee_email": "jane@example.com",
    "consignee_phone": "+44 7700 900123",
    "consignee_city": "London",
    "consignee_zip": "SW1A 2AA",
    "consignee_country": "GB",
    "sender_name": "Acme Corp",
    "sender_city": "New York",
    "sender_zip": "10001",
    "sender_country": "US"
  }'

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 — If an item has no hs_code, Duty Pro classifies it automatically using the product description. Even when you provide an HS code, Duty Pro resolves import and export variants for the specific origin and destination countries.
Pre-customs fee adjustment — Any pre-customs fees configured for the brand are distributed evenly across item values 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.
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_fees`	Sum of all additional fees
`total_amount`	Grand total: duties + taxes + 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. Subject line: "{Brand Name} — Customs Payment Required".
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 (i.e., there are fees to pay).

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):

Event	`held`	`canceled`	Trigger
Payment required	`true`	`false`	Shipment created with fees > 0
Payment received	`false`	`false`	Consignee completed payment
No payment required	`false`	`false`	Shipment created with fees = 0
Payment expired	`false`	`true`	Payment deadline passed without payment

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
`ABANDONED`	Payment deadline passed without payment