{ "openapi": "3.0.1", "info": { "title": "1688 Landed Cost API: Delivered Price, Duty & AliExpress Margin", "description": "1688 landed cost API: give your 1688 product rows (any 1688 scraper's dataset, or CSV) and a destination; get the delivered cost per unit (price tier, ECB rate, freight, insurance, duty, VAT) plus the AliExpress median and margin. Never loads 1688. Pay per computed product.", "version": "0.1", "x-build-id": "kawAjGFTLnKxTmR97" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sourcing-data-studio~1688-landed-cost-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sourcing-data-studio-1688-landed-cost-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sourcing-data-studio~1688-landed-cost-api/runs": { "post": { "operationId": "runs-sync-sourcing-data-studio-1688-landed-cost-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sourcing-data-studio~1688-landed-cost-api/run-sync": { "post": { "operationId": "run-sync-sourcing-data-studio-1688-landed-cost-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "datasetId": { "title": "Dataset of a 1688 scraper run", "type": "string", "description": "The dataset of a 1688 scraper run. Pick a named dataset from the list, or paste the dataset ID of your 1688 scraper run (17 letters and digits, on the run's Storage tab): the list shows named datasets only, and a scraper run's dataset has no name. username~dataset-name works too. The Actor only reads it: it never writes to it and never loads a 1688 page. The usual column names of 1688 scrapers are recognised; Column mapping covers the rest. To compute landed costs after every run of your scraper, add an integration to the scraper (its Integrations tab, then this Actor) with the input {\"datasetId\": \"{{resource.defaultDatasetId}}\"}. For AI agents: pass the dataset ID as a string, or use productsCsv when you have the rows as text." }, "productsCsv": { "title": "Products as CSV", "maxLength": 5000000, "type": "string", "description": "Your product rows as CSV text, one product per line, with the column names on the first line. Columns the Actor reads include titleEn (English title), title, priceCny (unit price in CNY), priceMinCny and priceMaxCny (a price range, priced at the maximum), moq, unitWeightKg, unitsPerCarton, cartonLengthCm, cartonWidthCm, cartonHeightCm, hsCode, domesticShippingCny, offerId and supplierName. Comma, semicolon or tab separated; put a cell that holds the separator in double quotes. Prices are read in CNY only. You can give a dataset and CSV rows together: the dataset is read first. At most 5,000,000 characters." }, "destination": { "title": "Destination", "enum": [ "BH", "SA", "AE", "OM", "QA", "KW", "GB", "US" ], "type": "string", "description": "Country the goods are imported into: Bahrain (BH, the default), Saudi Arabia (SA), United Arab Emirates (AE), Oman (OM), Qatar (QA), Kuwait (KW), United Kingdom (GB) or United States (US). Every amount of a row is in that country's currency. UK and US rows need an HS code (in the row or in HS code below); GCC rows without one get the 5 % GCC general rate.", "default": "BH" }, "quantity": { "title": "Quantity per product", "minimum": 1, "maximum": 10000000, "type": "integer", "description": "Units to cost for every product, for example 500. Leave empty to use each row's minimum order quantity (MOQ), or the minimum of its first price tier when that is higher. A quantity below it is raised to it (flag QTY_RAISED_TO_MOQ). The unit price is the price tier with the largest minimum quantity at or below this quantity." }, "maxItems": { "title": "Maximum products", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Maximum number of distinct products (offers) to read and compute in this run, at most 2,000. Repeated rows of one offer (one row per SKU) count once and are saved once. You pay only for the rows saved to the dataset: rows that are skipped (no price, no HS code for the UK or the US, a failed tariff lookup, a duplicate, excise goods) are free and are listed in the run summary. For AI agents: 10 is enough for a test.", "default": 100 }, "shippingMode": { "title": "Shipping mode", "enum": [ "airExpress", "airCargo", "sea" ], "type": "string", "description": "airExpress (courier: the chargeable weight is the larger of the actual weight and the volume / 5000, rounded up to 0.5 kg), airCargo (volume / 6000) or sea (LCL: priced per W/M, the larger of cubic metres and tonnes, at least 1).", "default": "airExpress" }, "freightRatePerKg": { "title": "Air freight rate (USD per kg)", "minimum": 0, "maximum": 1000, "type": "number", "description": "Your air freight rate in USD per chargeable kg, for example 6.5. Used with air express and air cargo. Without it freight is 0 and the row is flagged FREIGHT_NOT_INCLUDED: the Actor never invents a freight rate. With it, a row needs a unit weight (unitWeightKg); a row without one is skipped and not charged. Carton sizes, when the row has them, add the volumetric weight." }, "seaFreightRatePerCbm": { "title": "Sea freight rate (USD per W/M)", "minimum": 0, "maximum": 50000, "type": "number", "description": "Your sea freight (LCL) rate in USD per W/M (a cubic metre or a tonne, whichever is larger, at least 1), for example 95. Used with sea freight. Without it freight is 0 and the row is flagged FREIGHT_NOT_INCLUDED." }, "freightMinimumUsd": { "title": "Minimum freight charge (USD)", "minimum": 0, "maximum": 1000000, "type": "number", "description": "Minimum freight charge of your forwarder for each product row, in USD, for example 50. The freight of a row is never below it. 0 means no minimum.", "default": 0 }, "chinaShippingCny": { "title": "Shipping inside China (CNY)", "minimum": 0, "maximum": 10000000, "type": "number", "description": "Shipping inside China, from the supplier to your forwarder, in CNY for each product row (the whole order line), for example 30. Used for every row that has no value of its own: a domesticShippingCny value in the row wins. A row with neither counts 0 and is flagged DOMESTIC_SHIPPING_MISSING." }, "insurancePercent": { "title": "Insurance (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Cargo insurance in percent of the goods, the China shipping and the freight, for example 0.5. Leave empty for 0.5 % (flag INSURANCE_ASSUMED)." }, "sourcingFeePercent": { "title": "Sourcing agent fee (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Fee of a sourcing agent in percent of the goods value, for example 5. It is added to the landed total and is part of no value that duty is charged on. Default 0.", "default": 0 }, "paymentFxMarkupPercent": { "title": "Payment exchange markup (%)", "minimum": 0, "maximum": 50, "type": "number", "description": "What your bank or payment service adds to the exchange rate when you pay in CNY, in percent, for example 2. It raises the cost of the goods and of the China shipping in the landed total; customs values, duty, VAT and fees use the ECB cross rate without it. Default 0: the ECB cross rate as it is.", "default": 0 }, "sellPricePerUnit": { "title": "Sell price per unit", "minimum": 0, "maximum": 100000000, "type": "number", "description": "The price a buyer pays you per unit, in the destination currency, VAT included where the destination has VAT, for example 2.5 (BHD). With it every row gets profitPerUnit and marginPercent." }, "marketplaceFeePercent": { "title": "Marketplace fee (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Marketplace or payment fee in percent of the sell price without VAT, for example 15. Used with Sell price per unit. Default 0.", "default": 0 }, "fixedFeePerUnit": { "title": "Fixed fee per unit", "minimum": 0, "maximum": 100000000, "type": "number", "description": "Fixed fee per unit sold, in the destination currency, for example a fulfilment fee of 0.4. Used with Sell price per unit. Default 0.", "default": 0 }, "hsCode": { "title": "HS code", "maxLength": 20, "type": "string", "description": "HS or national tariff code for every row that has none of its own: 6, 8 or 10 digits, dots allowed (6402.99.98.00). A code in the row wins. UK: the 10-digit commodity code. US: the HTS code. GCC: optional; without a code the 5 % GCC general rate applies (flag HS_MISSING_GCC_GENERAL_RATE)." }, "computeWithSuggestedCode": { "title": "Compute UK and US rows with a suggested code", "type": "boolean", "description": "UK and US only. A row without an HS code is skipped and not charged, and the run summary gives up to 3 codes suggested by a search of its English title, each marked 'suggested, verify'. Switch this on to compute such rows with the top suggestion instead: the figures that depend on it get the basis suggested-code and the flag SUGGESTED_HS_CODE.", "default": false }, "shipmentType": { "title": "Shipment type", "enum": [ "commercial", "personal" ], "type": "string", "description": "commercial (the default: an import by a business) or personal. GCC low-value thresholds, which waive the duty on small consignments, apply to personal shipments only; VAT is still due.", "default": "commercial" }, "saudiDutyPercent": { "title": "Saudi Arabia duty (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Saudi Arabia only: the duty rate in percent to use instead of the 5 % GCC general rate, for example 12. Saudi Arabia charges more than 5 % on many tariff lines, and the Actor does not check the line (flag KSA_RATE_MAY_EXCEED_5)." }, "us301Percent": { "title": "US Section 301 duty (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "US only: the Section 301 list duty on goods from China in percent, for example 25 (Lists 1 to 3) or 7.5 (List 4A), applied to every US row of the run. This version has no verified table of the codes each Section 301 list covers, so without this field the list duties are left out and every US row is flagged US_301_NOT_INCLUDED. The 12.5 % forced-labour Section 301 duty (9903.05.31) is computed either way." }, "ukFirstDestinationCostGbp": { "title": "UK costs to the first destination (GBP)", "minimum": 0, "maximum": 1000000, "type": "number", "description": "UK only: costs in GBP from the UK border to the first destination in the UK, for example delivery to your warehouse, for each product row. They go into the import VAT base and the landed total. Default 0.", "default": 0 }, "ukAirFreightSharePercent": { "title": "UK share of air freight in the customs value (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "UK only: the share of the air freight that goes into the customs value, 0 to 100. Default 100, all of it, which is the conservative choice. The part left out still goes into the VAT base.", "default": 100 }, "usExcludeDomesticShipping": { "title": "US: leave China shipping out of the dutiable value", "type": "boolean", "description": "US only: leave the shipping inside China out of the dutiable value, as 19 CFR 152.103(a)(5)(i) allows when its conditions are met. Off by default: the dutiable value includes it, which is the conservative choice.", "default": false }, "usConsolidatedEntry": { "title": "US: one entry for all rows", "type": "boolean", "description": "US only: treat all US rows of the run as one customs entry, so the merchandise processing fee (MPF) is worked out once on their summed value and shared by value. Off by default: each row is its own entry (flag MPF_PER_ENTRY).", "default": false }, "marketCheck": { "title": "Check the AliExpress market", "type": "boolean", "description": "Look up each product's keyword on AliExpress and add the median, lowest and top-selling price and the margin against your landed cost per unit. The keyword comes from the English title or from the Search term column. A failed or blocked check is shown in the row and does not stop it. Default on.", "default": true }, "maxMarketChecks": { "title": "Maximum keywords to check", "minimum": 1, "maximum": 50, "type": "integer", "description": "At most this many distinct keywords are looked up on AliExpress in one run, 1 to 50 (default 10). Each takes about 10 seconds. Rows whose keyword is not looked up get the market status not-run. Keywords of UK and US rows without an HS code (skipped, free) are not looked up, nor more than your maximum cost per run pays rows for (plus 5).", "default": 10 }, "searchTermColumn": { "title": "Search term column", "maxLength": 200, "type": "string", "description": "Name of the column (or dotted path, such as product.keyword) of your rows that holds the AliExpress search term. Leave empty to use the English title." }, "columnMapping": { "title": "Column mapping", "maxItems": 30, "type": "array", "description": "Only for rows the Actor does not recognise: one target=path entry per line, where path is a column name or a dotted path of your rows, for example unitWeightKg=shipping.weightKg. Targets: offerId, offerUrl, title, titleEn, supplierName, tiers, priceMinCny, priceMaxCny, moq, unitWeightKg, unitsPerCarton, cartonLengthCm, cartonWidthCm, cartonHeightCm, hsCode, domesticShippingCny, searchTerm. An entry wins over the column the Actor would find itself.", "items": { "type": "string", "maxLength": 300 } }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy for the requests to the four sources: the ECB, the UK Trade Tariff, the US Harmonized Tariff Schedule and AliExpress. No proxy is needed, and the default is none. A proxy is never used to get around a refusal. The Actor sends no request to 1688.", "default": { "useApifyProxy": false } }, "maxRequestRetries": { "title": "Retries per request", "minimum": 0, "maximum": 6, "type": "integer", "description": "How many times a failed request is asked for again, with a growing wait between attempts. A request that a source refuses is not asked for again. A row whose tariff lookup failed is skipped and never charged. The default of 3 fits almost every run.", "default": 3 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Print detailed debug messages to the run log. Leave off unless you are investigating a problem; it does not change the results.", "default": false }, "feedback": { "title": "Feedback for the developer", "maxLength": 1000, "type": "string", "description": "Optional. Tell us which destination, cost line or column you need next, or what went wrong. It is saved with the run summary and does not change the results. Do not include personal data. AI agents may also use this field to report problems." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }