# 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.

| Value | What happens | Carriers |
|  --- | --- | --- |
| `guaranteed` | The duties and taxes are fixed when the label is created and charged to you. The recipient is not billed for them. Rates and labels return them as `prepaid_duties`, `prepaid_taxes` and `prepaid_import_fees`. | Wallet carriers, and eligible BYOA (Bring Your Own Account) carriers |
| `carrier_billed` | The carrier bills the actual duties and taxes to your own carrier account later. Rates and labels return an estimate as `estimated_duties`, `estimated_taxes` and `estimated_import_fees`. | BYOA carriers only |


## Requirements

* 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.


## Default When the Field Is Omitted

* 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.

## Which Carriers Support Each Value

`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.

| Carrier | Value |
|  --- | --- |
| Wallet carrier, guaranteed enabled | `["guaranteed"]` |
| Wallet carrier, guaranteed not enabled | `[]` |
| BYOA carrier, guaranteed enabled | `["guaranteed", "carrier_billed"]` |
| BYOA carrier, guaranteed not enabled | `["carrier_billed"]` |


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.

## Example

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


```json
{
  "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.

## Rates

* `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.


## Label Errors

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.

| Situation | HTTP status | `error_type` | `error_code` |
|  --- | --- | --- | --- |
| `duties_and_taxes_payment` without DDP, or with `customs.terms_of_trade_code: ddu` | `400` | `validation` | `field_conflict` |
| `duties_and_taxes_payment` combined with a partner-specific duties and taxes option | `400` | `validation` | `field_conflict` |
| `carrier_billed` on a Wallet carrier, including a label purchased from a rate ID | `400` | `validation` | `invalid_field_value` |
| `guaranteed` isn't available for this carrier and shipment | `400` | `validation` | `invalid_field_value` |
| BYOA carrier and no US managed funding source | `400` | `funding_sources` | `funding_source_missing_configuration` |
| The duties and taxes validation rejected the shipment, for example a missing or invalid HS code. The message starts with `Duties and taxes validation failed:` | `400` | `validation` | `invalid_field_value` |
| The duties and taxes service couldn't be reached or returned an error. Try again later. | `503` | `system` | `unspecified` |
| The funding source doesn't have enough funds. The label was purchased, then voided, and is not returned. | `402` | `account_status` | `insufficient_funds` |
| The duties and taxes couldn't be charged for another reason. The label was purchased, then voided, and is not returned. | `400` | `business_rules` | `unspecified` |


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.