Duties and Taxes Payment

When you ship internationally with DDP (Delivered Duty Paid), you pay the destination country's duties, taxes and import fees instead of the recipient. The advanced_options.duties_and_taxes_payment field controls how you pay them.

• The shipment must be DDP: set advanced_options.delivered_duty_paid to true or customs.terms_of_trade_code to ddp. Sending duties_and_taxes_payment without DDP, or with customs.terms_of_trade_code: ddu, returns a 400 field_conflict error.
• guaranteed needs an international shipment from a supported origin country, on a carrier that is enabled for guaranteed duties and taxes.
• guaranteed on a BYOA carrier is paid from your US managed funding source (ShipStation Balance). Only US origins are supported, and the funding source must have enough funds to cover the duties and taxes.
• carrier_billed is not available on Wallet carriers.

• BYOA carriers use carrier_billed. The carrier bills the duties and taxes to your carrier account, and your funding source is never charged for them unless you send guaranteed.
• Wallet carriers use guaranteed when the shipment is eligible for guaranteed duties and taxes.

Shipment responses return the value in effect. This includes the shipment returned by POST /v2/rates. Label responses don't include advanced_options. The value is null when the shipment isn't DDP, has no carrier, or uses a Wallet carrier and isn't eligible for guaranteed duties and taxes.

GET /v2/carriers, GET /v2/carriers/{carrier_id} and GET /v2/carriers/{carrier_id}/services all return supported_duties_and_taxes_payments. It is always present and can be empty.

Services that are domestic only return []. International services return their carrier's list.

This is a capability, not a promise for a specific shipment. guaranteed is listed when guaranteed duties and taxes are enabled for the carrier and your account for at least one origin country. A shipment can still be rejected because of its origin, its destination or its customs data. Your funding source isn't part of the check either, so a BYOA carrier can list guaranteed and still return funding_source_missing_configuration when you create a label.

The duties and taxes fields of a shipment. The other shipment fields (addresses, packages, customs items) are the same as for any international shipment.

{
  "shipment": {
    "carrier_id": "se-123456",
    "service_code": "ups_worldwide_expedited",
    "customs": {
      "contents": "merchandise",
      "non_delivery": "return_to_sender",
      "terms_of_trade_code": "ddp"
    },
    "advanced_options": {
      "duties_and_taxes_payment": "guaranteed"
    }
  }
}

Send this to POST /v2/labels, or send the same shipment to POST /v2/rates. You can also set the field when you create or update a shipment.

• guaranteed: rates include prepaid_duties, prepaid_taxes and prepaid_import_fees rate details. When guaranteed duties and taxes aren't available for a carrier and shipment, that carrier's rates are returned in invalid_rates with an error message saying so. This also happens for a BYOA carrier when your account has no US managed funding source. If the guaranteed amount can't be quoted, the carrier's rates aren't returned and the error is listed in errors.
• carrier_billed or omitted on a BYOA carrier: when an estimate is available for the shipment, rates include the estimated duties and taxes and the warning Duties & taxes amount is an estimate and may differ from final carrier charge. in warning_messages. If the estimate can't be calculated, the rate is still returned without the estimate and with the warning Duties & taxes estimate is unavailable for this rate.
• carrier_billed on a Wallet carrier: when the shipment's own carrier_id is a Wallet carrier, the request returns a 400 invalid_field_value error. When a Wallet carrier is in rate_options.carrier_ids, the response has an error for that carrier and no rates from it. Otherwise Wallet carriers are skipped.
• Rate estimates (POST /v2/rates/estimate) don't support the field. They always return estimated duties and taxes.
• Bulk rates (POST /v2/rates/bulk) don't apply the field when the rates are calculated, so a bulk rate can show estimated duties and taxes when you asked for guaranteed. When you read the results with GET /v2/shipments/{shipment_id}/rates or GET /v2/rates/{rate_id}, rates from carriers that can't provide the guaranteed duties and taxes you asked for are returned in invalid_rates. The label checks below still apply when you purchase a label from a bulk rate.

The first three rows apply to any value of the field. The next two apply only when you send guaranteed. The last four apply whenever the label gets guaranteed duties and taxes, including when you omit the field on an eligible Wallet carrier. Except where noted, no label is purchased.

All of these errors have error_source: shipengine. In the rare case that the label can't be voided automatically, the message says so. Contact support so you aren't billed for that label.

With carrier_billed, or when the field is omitted on a BYOA carrier, duties and taxes problems never stop the label. If the estimate can't be calculated (for example, because of missing customs data), the label is returned without the estimated duties and taxes.