Prepare the request
Landed cost API calculation에는 여러 input이 필요하며 workflow로 organize했습니다. Complete 후 shipping destination, cart item, shipping detail 기준 single request로 landed cost를 return할 수 있습니다.
각 workflow는 고유 required input을 가집니다. GraphQL은 necessary 이상 data 전달을 allow하지만 landed cost return에 required field만 있습니다. API reference에 clearly marked되어 all possible field를 확인할 수 있습니다.
Calculation guarantee를 원하면 일부 field가 conditionally required입니다.
Guaranteed landed cost calculate required field를 아래에 outline했습니다. Request 전 information 포함을 확인하세요.
Required inputs for guaranteed calculations
partyCreateWorkflowInputpartyCreateWorkflowInput은 involved party 및 location을 식별합니다. GraphQL API reference에서 full schema를 view하세요. Required field:
locationadministrativeAreaCode: 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.
personemail: The email address of the person.firstName: The first name of the person.lastName: The last name of the person.phone: The phone number of the person.
typeDESTINATION: Thelocation&personinformation for the shipping destination.ORIGIN: Thelocationinformation for the shipping origin. Thepersonassociated with the shipping origin is not required.
itemCreateWorkflowInputitemCreateWorkflowInput은 cart item을 list합니다. 많은 optional field가 있지만(API reference) 아래 field가 required입니다.
amount: The value of an single unit of the product being shipped, before being multiplied by quantity. Note that this differs from the postal definition of a postal item. If the item'squantityis 1, this the total cost of the item. If the item'squantityis >1, the API will multiple the itemamountby the item'squantityto get the total for the line item. Do not put the total price of all units of the item in theamount.currencyCode: The currency code for the item amount.quantity: The quantity of the item. The API will multiple the itemamountby the item'squantityto get the total for the line item.countryOfOrigin: The country where the item was manufactured.- One of the following (whichever is set as your item key preference. Your item key connects information stored in Catalog to the item in the cart and is used during label creation.)
productId: The item's product ID.sku: The item's SKU.
measurements(WEIGHT, LENGTH, WIDTH, HEIGHT)는 shipment rating 시 item cartonize 시에만 required합니다.
cartonsCreateWorkflowInputcartonsCreateWorkflowInput은 input 자체만 required입니다. GraphQL API reference에서 pass 가능 value를 view하세요. Zonos가 shipping cost를 calculate하면 carton dimension 및 weight pass가 important합니다.
shipmentRatingCreateWorkflowInputShipping service 및 cost를 이미 알 때 사용하는 workflow입니다. Enabled service cost calculate를 원하면 shipmentRatingCalculateWorkflow로 swap하세요.
shipmentRatingCreateWorkflowInput은 shipping cost를 communicate합니다. GraphQL API reference에서 full schema를 view하세요. Required field:
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.
landedCostWorkFlowInputlandedCostWorkFlowInput은 landed cost calculation preference를 dictate합니다. GraphQL API reference에서 full schema를 view하세요. Required field:
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).- If you use our landed cost guarantee, this value should always be
DDP_PREFERRED, which will provide a DDP quote when possible and a DAP quote is a DDP one is not allowed. UsingDAPinstead may result in landed costs no longer being guaranteed, as this typically results in duties and taxes paid at delivery.
- If you use our landed cost guarantee, this value should always be
endUse: Indicates if the goods are being sold to another business (FOR_RESALE) or for end use with a consumer (NOT_FOR_RESALE).tariffRate: Indicates the method that Zonos should use to calculate the tariff rates for this quote, in the event that there is a range of tariff rates that could be applied. *When using our landed cost guarantee, this should always beZONOS_PREFERRED.
Add calculated shipping: If you want Zonos to calculate the shipping cost for you, replace the
shipmentRatingCreateWorkflowwith theshipmentRatingCalculateWorkflow. Add thecartonizeWorkflowif you want Zonos to sort your items into cartons before finding the shipping cost (used for dimensional weight).
HS code and shipping options
GraphQL gives you the flexiblity to customize the request to your preference. There are a couple of options for how you include HS codes and shipping costs in the request.
HS codes
HS codes impact duty rates are therefore required. You can pass the HS code for each item or let Classify generate them.
Zonos highly recommends using product-specific HS codes as it leads to a more accurate landed cost quote. If you know your HS codes, pass the hsCode for each item during the itemCreateWorkflow.
HS code 전달 시 landed cost quote에서 Zonos가 on the fly validate합니다. Provided HS code invalid(exist하지 않음)이면 item을 on the fly re-classify하고 valid HS code를 사용합니다.
Product HS code generate 도움이 필요하면 Zonos Classify 및 request a classification을 참조하세요.
hsCode 미전달 시 Zonos Catalog에서 item stored HS code를 먼저 check합니다. 없으면 itemCreateWorkflow product detail field description, category, material 기준 Classify classification을 generate합니다. confidence scoring 기준 classification generate에 detail 부족 시 store default HS code를 사용합니다.
Shipping cost
Both the shipping service level and its cost impacts the duties, taxes, and fees and is therefore required. Zonos can calculate shipping or you can pass this to us.
To have Zonos calculate shipping costs, use the shipmentRatingCalculateWorkflow. The shipment options returned in the calculated shipping response will correlate with the serviceLevels you have assigned to shipping profiles in Dashboard.
Troubleshooting: If you are expecting a
serviceLevelin the response but it does not show up, please ensure that theserviceLevelis enabled and is supported by themethodyou selected.
Add the cartonizeWorkflow (which has no inputs) if you want Zonos to sort your items into cartons before finding the shipping cost (used for dimensional weight.
Shipment serviceLevel 및 amount를 알면 shipmentRatingCreateWorkflow portion에 전달할 수 있습니다. Associated carrier fee calculate 및 response return에 사용합니다.
Request a landed cost via API
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.
Use this request when you are having Zonos calculate the shipping cost as part of the Landed Cost request. We will then calculate duties and taxes on shipping if they are assessed by the destination country.
mutation CalculateLandedCost($parties: [PartyCreateWorkflowInput!]!$items: [ItemCreateWorkflowInput!]!$landedCostConfig: LandedCostWorkFlowInput!) { partyCreateWorkflow(input: $parties) { type id organization } itemCreateWorkflow(input: $items) { id amount productId } cartonizeWorkflow { id type items { item { id } } } shipmentRatingCalculateWorkflow { id amount } landedCostCalculateWorkflow(input: $landedCostConfig) { id duties { amount currency note } taxes { amount currency note } fees { amount currency note } }}Next step: Create an order
After you calculate a landed cost and receive the landedCostId from the API response, you should create an order to finalize the transaction in the Zonos system. Use the orderCreate mutation and pass in the landedCostId from your quote. Learn more about creating orders.
Request a landed cost in Dashboard
API 없이 Zonos Dashboard에서 directly landed cost calculate도 가능합니다. Calculation test, team training, customer inquiry quick quote에 helpful합니다.
Dashboard uses the same API endpoints described above, so the results will match what you'd get from direct API calls. This makes it a great way to validate your API integration or explore how different inputs affect the calculations.
Using the Dashboard calculator
With the landed cost calculator in Dashboard, you can get quotes with calculated shipping rates, create quotes with known shipping costs, or process multiple quotes in bulk.
Use this flow when you know the shipping service level and cost for your shipment.
- Go to Dashboard → Orders → Quotes
- Click New quote
- Optional — Modify the location of your ship-from address
- Select a Destination country from the dropdown
- Enter the shipping amount
- The service level is optional; adding it allows us to calculate applicable carrier fees
- Add the item details for the shipment
- When you enter a description, we automatically classify the product and generate an HS code
- You can overwrite the generated HS code if needed
- For multiple items, click Save and add another. Otherwise, click Save
- Optional — Click More options to change:
- Sale type to For resale
- Delivery mode to Delivery duties unpaid
- Click Get quote
- To make changes, click Edit form and modify any details
- Click Get quote again to update
A landed cost quote will appear on the right, including product, shipping, and import costs. Expand the quote to see detailed breakdowns of items, shipping, duties, taxes, and fees. All quotes are saved on the quotes page for future reference.
Edit existing quotes: Click Quote again in the top right to modify an existing quote rather than starting from scratch.
Benefits of using Dashboard
- No coding required — Generate quotes through a user-friendly interface
- Team training — Help non-technical team members understand landed cost components
- API validation — Verify your API integration produces expected results
- Customer support — Quickly generate quotes for customer inquiries
- Bulk processing — Handle multiple calculations efficiently (coming soon)
Dashboard quotes include the same detailed breakdowns available through the API, making it an excellent complement to your automated integration.
Calculate a landed cost
GraphQL로 duty, tax, fee를 calculate하세요.GraphQL
Zonos는 international shipment total landed cost — duty, tax, customs, broker, carrier additional fee 포함 — 를 calculate합니다. 대부분 final bill을 직접 pay하고 calculate한 amount를 charge하여 calculation을 guarantee합니다. 일부 경우 guarantee 없이 landed cost를 사용할 수 있으며 calculate와 actual charge 차이 responsibility를 assume합니다.