リクエストを準備
Landed Cost API の計算には複数の入力が必要で、ワークフローに整理しています。完了後、配送先、カート内品目、配送詳細に基づく Landed Cost を単一リクエストで取得できます。
各ワークフローには独自の必須入力があります。GraphQL では必要以上のデータを渡せますが、Landed Cost を返すには特定フィールドのみが必須です。API reference ですべての可能なフィールドを確認でき、必須は明確にマークされています。
計算を保証したい場合、一部フィールドは条件付き必須であることに注意してください。
以下に、保証付き Landed Cost 計算に必要なすべてのフィールドを示します。リクエスト前にこの情報が含まれていることを確認してください。
保証計算に必要な入力
partyCreateWorkflowInputpartyCreateWorkflowInput は関係者とその所在地を識別します。GraphQL API reference で完全なスキーマを確認してください。必須フィールド:
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 はカート内の品目を一覧表示します。任意フィールドは多数あります（API reference ですべて確認可能）が、以下が必須です。
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.
The measurements (WEIGHT, LENGTH, WIDTH, HEIGHT) are only required if you want to cartonize your items when getting a shipment rating.
cartonsCreateWorkflowInputcartonsCreateWorkflowInput 自体の入力のみが必要です。GraphQL API reference で渡せるすべての値を確認できます。Zonos が配送コストを計算する場合、カートンの寸法と重量を渡すことが重要です。
shipmentRatingCreateWorkflowInputThis workflow is used when you already know the shipping service and cost; if you want Zonos to calculate these costs for services you have enabled, swap this workflow out and use the shipmentRatingCalculateWorkflow instead.
shipmentRatingCreateWorkflowInput は配送コストを伝えます。GraphQL API reference で完全なスキーマを確認してください。必須フィールド:
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 計算の設定を指定します。GraphQL API reference で完全なスキーマを確認してください。必須フィールド:
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 コードと配送オプション
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 コード
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.
If you pass an HS code, Zonos will validate it on the fly when getting a landed cost quote. If the HS code you provided is invalid (meaning it does not exist), Zonos will re-classify your item on the fly and use the new, valid HS code instead of your provided one.
If you need help generating HS codes for your products, learn about Zonos Classify and how to request a classification.
If you do not pass Zonos an hsCode, we'll first check Zonos Catalog to see if you have an HS code stored for your item. If you don't, we'll call Classify to generate a classification to power your landed cost calculation based on the following itemCreateWorkflow product detail fields: description, category, and material. If your product detail fields are not detailed enough to generate a classification based on Classify's confidence scoring, the default HS code assigned to your store will be used.
配送コスト
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.
If you know the serviceLevel and amount for a shipment, you can pass those in the shipmentRatingCreateWorkflow portion of the request. We will use those values to calculate any associated carrier fees and return those in the response.
API 経由で Landed Cost をリクエスト
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 } }}次のステップ: 注文を作成
Landed Cost を計算し、API 応答から landedCostId を受け取ったら、Zonos システムで取引を確定するため注文を作成してください。orderCreate ミューテーションを使用し、見積もりの landedCostId を渡します。注文作成の詳細を参照してください。
Dashboard で Landed Cost をリクエスト
Zonos Dashboard で API を使わずに Landed Cost を直接計算できます。計算のテスト、チームトレーニング、顧客問い合わせへの迅速な見積もりに役立ちます。
Dashboard は上記と同じ API エンドポイントを使用するため、直接 API 呼び出しと同じ結果が得られます。API 統合の検証や、入力の違いが計算に与える影響の探索に最適です。
Dashboard 計算機の使用
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.
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.
Landed Cost を計算
GraphQL で関税、税、手数料を計算します。GraphQL
Zonos は国際配送の総 Landed Cost（関税、税、税関・ブローカー・キャリアによる追加手数料を含む）を計算します。多くの場合、最終請求を自社で支払い、計算額どおりに請求することでこれらの計算を保証します。一部のケースでは保証なしで Landed Cost を使用でき、その場合、計算と実際の請求の差額についてお客様が責任を負います。