Calculate landed cost

HomeUPS® Global Checkout Landed cost Calculate landed cost

Calculate a landed cost

Calculate duties, taxes, and fees.

GraphQL

UPS calculates the total landed cost for shipments, which includes duties, taxes, and any additional fees that customs, brokers, or shipping carriers may charge. We often guarantee these calculations by paying the duty, tax, and fee bill ourselves while charging you exactly what we calculate.

Prepare the mutation input 

Calculating a landed cost via GraphQL API involves multiple steps; we've organized these steps into workflows. In the end, you'll have everything you need to make one call to get a landed cost based on the shipping destination, items in the cart, and shipping.

Each workflow needs specific input data. GraphQL allows you to include more information than required; please refer to our full API reference to see all possible fields. Required fields are marked as such in our API reference, but this mark only applies to fields that are required for functionality. A few additional fields are required when using our guarantee.

Below, we've listed all required fields for calculating a guaranteed landed cost. Make sure you have this information ready.

Required inputs for guaranteed calculations

partyCreateWorkflowInput

The partyCreateWorkflowInput identifies the involved parties and their locations. View the full schema in our GraphQL API reference. Required fields are:

  • location
    • administrativeAreaCode: The state or province code, in two letters. Only required for CA and BR.
    • countryCode: The two-letter ISO code of the country.
    • line1: The first line of the address.
    • postalCode: The postal code or zip code of the address.
  • type
    • DESTINATION: The location & person information for the shipping destination.
    • ORIGIN: The location information for the shipping origin. The person associated with the shipping origin is not required.

When you go to ship an order generated by a UPS® Global Checkout quote, destination information will be validated. If there is a mismatch between countryCode on the quote and the shipment, the shipment will not be guaranteed. We will also validate against address and postal code data to ensure that the same landed cost quote is not used for multiple shipments.

itemCreateWorkflowInput

The itemCreateWorkflowInput lists the items in the cart. There are many optional fields (see all possibilities in our API reference), but the fields below are required.

  • amount: The price of the item.
  • currencyCode: The currency code for the item amount.
  • quantity: The quantity of the item.
  • One of the following:
    • productId: The item's product ID.
    • sku: The item's SKU.

Note: While countryOfOrigin is not a required field, UPS strongly recommends including it. With changing tariff regulations, country of origin is becoming increasingly important for accurate classification and duty calculation.

When you go to ship an order generated by a UPS® Global Checkout quote, we will validate against quantities and product ID or SKU. If there are SKUs present in the shipment that were not provided here or quantities exceed what is quoted, the shipment will not be guaranteed.

cartonsCreateWorkflowInput

The cartonsCreateWorkflowInput only requires the input itself. View the full schema in our GraphQL API reference to see all values that can be passed.

shipmentRatingCreateWorkflowInput

The shipmentRatingCreateWorkflowInput communicates the shipping cost. View the full schema in our GraphQL API reference. Required fields are:

  • amount: The shipping cost.
  • currencyCode: The currency code of the shipping cost.
  • serviceLevelCode: The code indicating the shipping service level used in the shipment rating.
landedCostWorkflowInput

The landedCostWorkflowInput only requires the input itself. View the full schema in our GraphQL API reference. Fields that will alter the landed cost quote provided are:

  • calculationMethod: Indicates your preference for how you plan to ship: DDP (prepaid duties and taxes) or DAP (either duties and taxes are paid at delivery, or if a remittance scheme applies, they are remitted via a tax ID).
    • The default value will always be DDP_PREFERRED, which will provide a DDP quote when possible and a DAP quote is a DDP one is not allowed. Using DAP instead may result in the landed cost no longer being guaranteed, as this typically results in duties and taxes paid at delivery.
  • endUse: Indicates if the goods are being sold to another business (FOR_RESALE) or for end use with a consumer (NOT_FOR_RESALE); this is the default value.

HS codes in landed cost calculations

HS codes are used to calculate duties and taxes for cross-border shipments. You can either provide a product-specific HS code for each item or let UPS generate one automatically based on item details. If you have an HS code, pass it in the hsCode field during the itemCreateWorkflow.

To learn how HS codes are validated, auto-classified, and how fallback logic works, visit our HS codes in Global Checkout doc.

Send the mutation 

Once you have the required input data, send the GraphQL mutation to the API endpoint using your chosen client library or tool. Here are some examples of how you can structure the mutation. If you run into any issues, please view see here.

This landed cost request shows only the details that are required to get a landed cost quote that can be provided to your customer at checkout.

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
mutation {
  partyCreateWorkflow(
    input: [
      {
        type: ORIGIN
        location: {
          postalCode: "84790"
          countryCode: US
          administrativeAreaCode: "UT"
        }
      }
      {
        type: DESTINATION
        location: {
          administrativeAreaCode: "ON"
          postalCode: "K1L 6B6"
          countryCode: CA
        }
      }
    ]
  ) {
    id
    type
  }
  itemCreateWorkflow(
    input: [
      {
        amount: 60.5
        currencyCode: GBP
        productId: "34341"
        countryOfOrigin: CN
        quantity: 1
      }
    ]
  ) {
    id
    hsCode
    countryOfOrigin
    productId
  }
  cartonsCreateWorkflow(input: {}) {
    id
  }
  shipmentRatingCreateWorkflow(
    input: {
      serviceLevelCode: "ups.standard"
      amount: 25
      currencyCode: GBP
      displayName: "UPS Standard"
    }
  ) {
    id
    amount
    serviceLevelCode
  }
  landedCostCalculateWorkflow(input: {}) {
    id
    amountSubtotals {
      duties
      taxes
      fees
      shipping
      items
    }
  }
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "data": {
    "partyCreateWorkflow": [
      {
        "id": "party_a030a73c-fdb2-4b0b-80f2-282f78784591",
        "type": "ORIGIN"
      },
      {
        "id": "party_fbbf0b79-8cdc-4b79-836f-6bd5c6f580ae",
        "type": "DESTINATION"
      }
    ],
    "itemCreateWorkflow": [
      {
        "id": "item_d4457a76-4c25-4474-bfd4-7d00a4d3e29a",
        "hsCode": "6110.20.2010",
        "countryOfOrigin": "CN",
        "productId": "34341"
      }
    ],
    "cartonsCreateWorkflow": [
      {
        "id": "carton_d4545c00-de10-4dff-ab87-08fc5cdda1b8"
      }
    ],
    "shipmentRatingCreateWorkflow": {
      "id": "shipment_rating_c217b4a6-bccd-4eb6-8456-4cf8e46e84fe",
      "amount": 25,
      "serviceLevelCode": "ups.standard"
    },
    "landedCostCalculateWorkflow": [
      {
        "id": "lc-7ecf611464b148c4a3387d854fffa10b",
        "amountSubtotals": {
          "duties": 0.0,
          "taxes": 7.87,
          "fees": 0.0,
          "shipping": 25.0,
          "items": 60.5
        }
      }
    ]
  }
}

Was this page helpful?

© 2025 UPSUPS docs
On this page:
  • Calculate a landed cost
  • Prepare the mutation input
  • Send the mutation