Starting September 22nd, CBP will begin testing the implementation of the Entry Type 13 filing, which requires additional PGA (Partner Government Agency) data for package items. Two new item-level fields are available on the package submission endpoints (/packages and /shipments):
pgaData — PGA data elements for the item, as type/value pairs
\nnotForMedicalUse — attestation that the product is not intended for medical use
\nThese fields are optional for now, but will become required in the future, depending on the HTS code of the item: HTS codes carrying PGA indicators (FDA, APHIS/Lacey Act, Fish & Wildlife, EPA, ...) will demand the corresponding data elements, and packages whose items are missing them will be rejected. See the field documentation on the Create Packages and Create Shipment endpoints for the field shapes and the list of data element types, use the Get HTS Code Requirements endpoint (GET /hts/{htsCode}/requirements) to discover which data elements a specific HTS code demands, and start submitting the data early to avoid disruption when enforcement begins.
The International Mail Duty Collection API allows developers to integrate comprehensive customs and duty processing capabilities within their shipping and e-commerce applications. The API offers package creation, container management, shipment processing, and automated duty calculation features.
\nGetting Started: For additional help, please email us at support@safepackage.com.
\nAccount Setup: To request API access, please email api-access@safepackage.com with your business information and integration requirements. Our team will provision your account and provide the necessary credentials for authentication.
\nPackage Management
Create and manage individual mail packages with detailed customs information including country of origin, declared values, and item details.
Container Operations
Group packages into containers with comprehensive entry route information including flight numbers, vessel details, transport types, carrier codes, and port of entry data.
Shipment Processing
Process complete shipments with multiple containers and packages in a single operation. This powerful endpoint combines package creation, container management, and automatic associations in one streamlined workflow.
The International Mail Duty Collection API uses JWT Bearer token authentication via OAuth2 integration. All API requests require proper authentication using JWT Bearer tokens.
\nAuthentication Setup
Obtain your JWT tokens from our OAuth2 authentication service at https://auth.dutycollection.safepackage.com. Configure your application with the client credentials provided during account setup.
Automatic Duty Calculation
The API automatically calculates duties and tariffs based on country of origin, declared values, current trade policy and tariff rates.
Production Environment
\nBase URL: https://dutycollection.safepackage.com
\nAuthentication URL: https://auth.dutycollection.safepackage.com
\nSandbox Environment
\nAuthentication URL: https://auth.dutycollection-sandbox.safepackage.com
\nGetting Help
\nEmail Support: support@safepackage.com
\nAccount Setup: Email api-access@safepackage.com for account provisioning
\nIntegration Assistance: Custom implementation support available
\nThe API allows the submittal of item HTS code information, which helps to differentiate between taxable and exempt goods. Listed below is a table of eligible HTS code prefixes. If an HTS code begins with one of the listed prefixes, it is eligible for a duty exemption.
\n2 separate HTS codes can also be used to claim tax exemption, but are part of specific cases:
\n9804.00.30 - HTS code for items specified as gifts, where all items in the package are eligible for duty exemption if the they all have the specified HTS code and the total declared value of the package does not exceed $100
\n9801.00.10 - Returns, items whose country of origin is the US which are being returned to the country
\nAuthentication samples for obtaining an access token from the authentication URL
\n","_postman_id":"01e20b65-0b3f-4a66-ae64-4b5499053651"},{"name":"Packages","item":[{"name":"Create Packages","id":"42da45fe-770f-4c25-b704-67ff42fca79b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer ","description":"JWT token for authentication
\n"}],"body":{"mode":"raw","raw":"{\n \"packages\": [\n {\n \"trackingReference\": \"US123456789US\",\n \"items\": [\n {\n \"countryOfOrigin\": \"CN\",\n \"totalDeclaredValue\": 77.97,\n \"description\": \"Men's knitted cotton t-shirt, short sleeve\",\n \"htsCode\": \"6109.10.00.12\",\n \"quantity\": 3,\n \"customsQuantities\": [\n {\n \"value\": 0.6,\n \"unitOfMeasure\": \"Kg\"\n }\n ]\n },\n {\n \"countryOfOrigin\": \"JP\",\n \"totalDeclaredValue\": 91.0,\n \"description\": \"Ceramic coffee mug, hand painted\",\n \"htsCode\": \"6912.00.44.00\",\n \"quantity\": 2,\n \"singleUnitWeight\": {\n \"value\": 0.7,\n \"unitOfMeasure\": \"Kilograms\"\n },\n \"pgaData\": [\n {\n \"type\": \"IntendedUse\",\n \"value\": \"Household tableware for hot beverages (food contact)\"\n },\n {\n \"type\": \"ProductCode\",\n \"value\": \"23FGH07\"\n },\n {\n \"type\": \"CountryOfProduction\",\n \"value\": \"JP\"\n },\n {\n \"type\": \"TradeBrandName\",\n \"value\": \"Sakura Ceramics\"\n },\n {\n \"type\": \"ProductSpecificDescription\",\n \"value\": \"Hand painted ceramic coffee mug, 350 ml\"\n },\n {\n \"type\": \"PackagingLevels\",\n \"value\": \"1 box containing 2 mugs\"\n }\n ],\n \"notForMedicalUse\": true\n }\n ]\n },\n {\n \"trackingReference\": \"CN987654321CN\",\n \"items\": [\n {\n \"countryOfOrigin\": \"DE\",\n \"declaredValue\": 75.0,\n \"description\": \"Leather wallet, bovine\",\n \"htsCode\": \"4202.31.60.00\",\n \"quantity\": 1,\n \"weight\": {\n \"value\": 0.2,\n \"unitOfMeasure\": \"Kilograms\"\n }\n }\n ]\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://dutycollection.safepackage.com/api/v1/packages","description":"Creates multiple packages in a single operation. Each package can contain multiple items with different countries of origin and declared values.
\ntrackingReference (string, required): Unique identifier for the package
\nFormat: UPU S10 (2 letters + 9 digits + 2 letters) or USPS IMPB (22/26/30/34 digits)
\nExample: US123456789US, CN987654321CN
Must be unique across all packages in the system
\nitems (array, required): Collection of items within the package
\nMinimum: 1 item required per package
\nMaximum: No limit on items per package
\ncountryOfOrigin (string, required): ISO country code of item origin
\nFormat: 2-letter ISO country code
\nExamples: CN (China), JP (Japan), DE (Germany), US (United States)
Used for tariff calculation and customs processing
\nDeclared value — exactly one of the following fields must be set per item:
\ntotalDeclaredValue (number, recommended): Declared monetary value for the whole line (all units together)
\ndeclaredValue (number, deprecated): Legacy field kept for existing integrations — carries the line total, not a per-unit value
\nFormat: Decimal number with up to 2 decimal places, in your configured input currency (USD unless agreed otherwise)
\nThe sum of all item line totals in a package must not exceed $2,500 (postal clearance limit)
\ndescription (string, required in practice): Human-readable description of the item
\nExample: Men's knitted cotton t-shirt, short sleeve
Drives HTS classification whenever the submitted htsCode is not a full 10-digit code
htsCode (string, optional): Harmonized Tariff Schedule (HTS) code, dotted or plain digits
\nAccepted at 6, 8 or 10 digits — but duties are always calculated against a full 10-digit schedule code
\nA 6/8-digit code is treated as a classification hint; the remaining digits are resolved from the item description
Submit the full 10-digit code (e.g. 6109.10.00.12) for deterministic classification and pricing
quantity (number, optional): Number of units in the line. Whole number, minimum 1, defaults to 1
\n{ \"value\": ..., \"unitOfMeasure\": ... } object form is no longer acceptedcustomsQuantities (array, optional): Line-total quantities in the units a tariff rate can bill on
\nEach entry: value (number, > 0) and unitOfMeasure (string): one of Kg, Gram, Dozen, SquareMeter, CubicMeter, MetricTon, Liter, ProofLiter, Barrel, Gross, Pair, Per1000, Number
At most one entry per unit of measure
\nInclude a mass entry (e.g. { \"value\": 0.6, \"unitOfMeasure\": \"Kg\" } for the whole line) whenever the tariff bills on weight — the calculation is rejected otherwise
singleUnitWeight (object, deprecated): Weight of the whole line (despite the name), folded into customsQuantities as a mass entry
Pounds, Kilograms, Gramsweight (object, deprecated): Same meaning as singleUnitWeight — the line-total weight; only one of the two may be set
Since July 24th, 2026 duties are calculated against the full HTS schedule: every item must resolve to a valid 10-digit HTS code — from the submitted htsCode or from the description via classification — or the package is rejected. A mass entry in customsQuantities is required whenever the resolved tariff bills on weight.
pgaData (array, optional for now): PGA (Partner Government Agency) data elements for the item, driven by the item's HTS code
\nEach entry carries a type (string enum) and a value (string, max 1000 characters)
\nA type may appear at most once per item
\ntype values: IntendedUse, IntendedUseCode, ProductCode, CountryOfProduction, TradeBrandName, ProductSpecificDescription, ManufacturerFei, ImporterOfRecordFei, PointOfContact, ShipperFei, DeliveredToPartyFei, PackagingLevels, ProductId, CitationCodes, ManufactureDate, ManufacturePlace, ProductTestDate, TestingLaboratory, CountryOfHarvest, ScientificNameGenus, ScientificNameSpecies, CommonName, PermitNumber, ManufacturerId, TscaCertification
Which types are needed depends on the PGA indicators of the item's HTS code — e.g. FDA-flagged codes (food contact, cosmetics) call for IntendedUse, ProductCode, CountryOfProduction, TradeBrandName, ProductSpecificDescription and PackagingLevels
notForMedicalUse (boolean, optional for now, defaults to false): attests the product is not intended for medical use
trueOnce the Entry Type 13 requirement is enforced for your account, packages failing the PGA rules are rejected with error codes V_PgaRequiredInformationMissing, V_HtsCodeNotApprovedForShipping or V_NotForMedicalUseAttestationRequired
Returns an array of created packages with:
\nPackage ID (system generated)
\nTracking reference (as provided)
\nTotal declared value (calculated)
\nTotal duties owed (calculated)
\nIndividual items with calculated duties
\nCreation timestamp
\nBulk import of packages from external systems
\nBatch processing of mail items
\nInitial package registration before container assignment
\nTracking references must be unique system-wide
\nEach package must have at least one item
\nDeclared values must be positive numbers
\nCountry codes must be valid ISO codes
\nDuties are automatically calculated based on origin country and value
\nPackage management operations for individual mail items with customs information.
\n","_postman_id":"b0e0e8d2-1faf-48d0-a11e-a0f704b87c75"},{"name":"Containers","item":[{"name":"Create Containers","id":"e3ca7a29-e8d8-422f-a8b4-9ff11671162e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer "}],"body":{"mode":"raw","raw":"{\n \"containers\": [\n {\n \"trackingReference\": \"CONT001-AA1234\",\n \"entryRoute\": {\n \"flightOrTripNumber\": \"AA1234\",\n \"transportType\": \"Air\",\n \"carrierCode\": \"AA\",\n \"arrivalPortCode\": \"4701\",\n \"entryTimestamp\": \"2024-01-15T10:30:00Z\"\n },\n \"packages\": [\"US123456789US\", \"CN987654321CN\"]\n },\n {\n \"trackingReference\": \"CONT002-DL53\",\n \"entryRoute\": {\n \"flightOrTripNumber\": \"DL53\",\n \"transportType\": \"Air\",\n \"carrierCode\": \"DL\",\n \"arrivalPortCode\": \"4701\",\n \"entryTimestamp\": \"2024-01-16T08:00:00Z\"\n },\n \"packages\": [\"DE456789123DE\"]\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://dutycollection.safepackage.com/api/v1/containers","description":"Creates multiple containers in a single operation, each with their own entry route information and package assignments.
\ntrackingReference (string, required): Unique identifier for the container
\nFormat: Alphanumeric string, max 50 characters
\nExample: CONT001-AA1234, CONT002-DL53
Must be unique across all containers
\nOften includes flight/vessel reference for easy identification
\npackages (array, required): List of package tracking references
\nFormat: Array of strings
\nReferences must match existing packages created via /packages endpoint
Minimum: 1 package per container
\nExample: [\"US123456789US\", \"CN987654321CN\"]
flightOrTripNumber (string, required): Transportation identifier
\nFor Air: Flight number (e.g., AA1234, DL53, UA567)
For Vessel: Voyage number (e.g., MAEU-123, COSCO-456)
For Ground: Trip/route number
\nMax length: 50 characters
\ntransportType (string, required): Mode of transportation
\nValues: Air, Vessel, Ground
Case-sensitive enumeration
\nUsed for compliance and routing decisions
\ncarrierCode (string, required): Transportation company code
\nExamples: AA (American Airlines), DL (Delta), UA (United)
Standard industry codes preferred
\nMax length: 10 characters
\narrivalPortCode (string, required): CBP port of entry code
\nFormat: Standard CBP port codes
\nExample: 4701 for specific port locations
Used for customs processing and duty collection
\nMax length: 10 characters
\nentryTimestamp (string, required): Arrival date and time
\nFormat: ISO 8601 timestamp with timezone
\nExample: 2024-01-15T10:30:00Z
Used for scheduling and compliance reporting
\nMust be valid future or past timestamp
\nReturns an array of created containers with:
\nContainer ID (system generated)
\nTracking reference
\nEntry route information
\nAssociated package references
\nCreation timestamp
\nContainer tracking references must be unique
\nAll referenced packages must exist before container creation
\nEntry timestamp should align with actual arrival schedules
\nPort codes must be valid CBP locations
\nContainer management for grouping packages with transport and entry route information.
\n","_postman_id":"797c136c-b478-4ba1-b922-f5baef04a8b4"},{"name":"Duties","item":[{"name":"Calculate Duties","id":"f740a432-625d-4e0c-b3c5-27d3a4c3aad5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer "}],"body":{"mode":"raw","raw":"{\n \"items\": [\n {\n \"reference\": \"ITEM-001\",\n \"countryCode\": \"CN\",\n \"price\": 25.99,\n \"quantity\": 3,\n \"htsCode\": \"4908.90.00\"\n },\n {\n \"reference\": \"ITEM-002\",\n \"countryCode\": \"JP\",\n \"price\": 89.99,\n \"quantity\": 3,\n \"htsCode\": \"4908.90.00\"\n },\n {\n \"reference\": \"ITEM-003\",\n \"countryCode\": \"DE\",\n \"price\": 150.00,\n \"quantity\": 3,\n \"htsCode\": \"4908.90.00\"\n }\n ],\n \"entryDate\": \"2024-01-15\"\n}","options":{"raw":{"language":"json"}}},"url":"https://dutycollection.safepackage.com/api/v1/duties/calculate","description":"Calculates customs duties for a collection of items based on their country of origin, declared value, and entry date.
\nThis endpoint provides duty calculation functionality without creating any persistent records. It's useful for:
\nitems (array, required): Collection of items to calculate duties for
\nentryDate (string, required): Date when items will enter the country
\n2024-01-15reference (string, required): Unique identifier for the item
\nITEM-001, SKU-ABC123, PRODUCT-456countryCode (string, required): ISO country code of item origin
\nCN (China), JP (Japan), DE (Germany), US (United States)price (number, required): Declared monetary value of the item
\n25.99, 150.00, 1250.50Returns calculated duty information for each item:
\nDuty calculation services for estimating customs duties without creating persistent records.
\n","_postman_id":"732aa7b7-8fce-490b-bcc1-028fbc7b2cc8"},{"name":"HTS","item":[{"name":"Get HTS Code Requirements","id":"7f76c3ff-c3ab-46fe-b150-f61d0b516a6f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://dutycollection.safepackage.com/api/v1/hts/6101.30.15.00/requirements","description":"Returns what an item classified under the given HTS code must carry when it is submitted: the data its duty calculation needs, and the PGA (Entry Type 13) data its filing needs. Query it before submitting packages to know up front which item fields to collect.
\nhtsCode (string, required): the HTS code to query, dotted or plain digits (e.g. 6101.30.15.00 or 6101301500)
404 Not FoundhtsCode (string): the queried code in dotted form
\ndescription (string): the full hierarchical tariff schedule description of the code
\nrequiresSpecificQuantityUnit (boolean): true when a rate on the code bills per unit (e.g. ¢/kg), so an accurate duty needs the item quantity expressed in one of the required units
\nrequiredQuantityUnits (array of strings): the units a customsQuantities entry must supply (e.g. Kg)
acceptedQuantityUnits (array of strings): all units the tariff schedule lists for the code
\nrequiredComponents (array of strings): component HTS classifications CBP declares separately (e.g. watch movements); items under the code must submit a components entry per listed code
null when no PGA indicators are recorded for the code — no PGA data is needed. Otherwise:
indicators (array of strings): the PGA flag codes of the HTS code (e.g. FD1, AL2)
approvedForShipping (string): Approved, ConditionallyApproved, NotApproved or Undetermined — once Entry Type 13 enforcement is on, only Approved and ConditionallyApproved codes are accepted
requiresNotForMedicalUseAttestation (boolean): when true, items under the code must submit notForMedicalUse: true
requiredData (array of strings): the pgaData types an item under the code must submit (see the Create Packages documentation for the full type list)
Query the tariff schedule for what an item under a given HTS code must carry at submission.
\n","_postman_id":"cd97aba3-25d6-4e34-83dd-ab2cd932f9d7"},{"name":"Shipments","item":[{"name":"Create Shipment (Complete Workflow)","id":"e1bc4070-d18b-4dc9-88ae-32d8e7ed8831","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer "}],"body":{"mode":"raw","raw":"{\n \"containers\": [\n {\n \"trackingReference\": \"CONT001-AA1234\",\n \"entryRoute\": {\n \"flightOrTripNumber\": \"AA1234\",\n \"transportType\": \"Air\",\n \"carrierCode\": \"AA\",\n \"arrivalPortCode\": \"4701\",\n \"entryTimestamp\": \"2024-01-15T10:30:00Z\"\n },\n \"packages\": [\n {\n \"trackingReference\": \"US123456789US\",\n \"items\": [\n {\n \"countryOfOrigin\": \"CN\",\n \"description\": \"Cotton t-shirt\",\n \"htsCode\": \"6109.10.00\",\n \"quantity\": 3,\n \"totalDeclaredValue\": 77.97,\n \"customsQuantities\": [\n {\n \"value\": 1.5,\n \"unitOfMeasure\": \"Kg\"\n }\n ]\n },\n {\n \"countryOfOrigin\": \"CN\",\n \"description\": \"Phone case\",\n \"htsCode\": \"3926.90.99\",\n \"quantity\": 2,\n \"totalDeclaredValue\": 31.0,\n \"customsQuantities\": [\n {\n \"value\": 0.2,\n \"unitOfMeasure\": \"Kg\"\n }\n ]\n }\n ]\n },\n {\n \"trackingReference\": \"JP456789012JP\",\n \"items\": [\n {\n \"countryOfOrigin\": \"JP\",\n \"description\": \"Ceramic mug\",\n \"htsCode\": \"6912.00.48\",\n \"quantity\": 1,\n \"totalDeclaredValue\": 89.99,\n \"customsQuantities\": [\n {\n \"value\": 0.35,\n \"unitOfMeasure\": \"Kg\"\n }\n ],\n \"pgaData\": [\n {\n \"type\": \"IntendedUse\",\n \"value\": \"Household tableware for hot beverages (food contact)\"\n },\n {\n \"type\": \"ProductCode\",\n \"value\": \"23FGH07\"\n },\n {\n \"type\": \"CountryOfProduction\",\n \"value\": \"JP\"\n },\n {\n \"type\": \"TradeBrandName\",\n \"value\": \"Sakura Ceramics\"\n },\n {\n \"type\": \"ProductSpecificDescription\",\n \"value\": \"Hand painted ceramic coffee mug, 350 ml\"\n },\n {\n \"type\": \"PackagingLevels\",\n \"value\": \"1 box containing 2 mugs\"\n }\n ],\n \"notForMedicalUse\": true\n }\n ]\n }\n ]\n },\n {\n \"trackingReference\": \"CONT002-DL53\",\n \"entryRoute\": {\n \"flightOrTripNumber\": \"DL53\",\n \"transportType\": \"Air\",\n \"carrierCode\": \"DL\",\n \"arrivalPortCode\": \"4701\",\n \"entryTimestamp\": \"2024-01-15T14:20:00Z\"\n },\n \"packages\": [\n {\n \"trackingReference\": \"DE789012345DE\",\n \"items\": [\n {\n \"countryOfOrigin\": \"DE\",\n \"description\": \"Leather wallet\",\n \"htsCode\": \"4202.31.60\",\n \"quantity\": 1,\n \"totalDeclaredValue\": 150.0,\n \"customsQuantities\": [\n {\n \"value\": 0.2,\n \"unitOfMeasure\": \"Kg\"\n }\n ]\n }\n ]\n },\n {\n \"trackingReference\": \"FR012345678FR\",\n \"items\": [\n {\n \"countryOfOrigin\": \"FR\",\n \"description\": \"Silk scarf\",\n \"htsCode\": \"6214.10.00\",\n \"quantity\": 1,\n \"totalDeclaredValue\": 75.25,\n \"customsQuantities\": [\n {\n \"value\": 0.15,\n \"unitOfMeasure\": \"Kg\"\n }\n ]\n },\n {\n \"countryOfOrigin\": \"IT\",\n \"description\": \"Glass vase\",\n \"htsCode\": \"7013.99.50\",\n \"quantity\": 1,\n \"totalDeclaredValue\": 42.8,\n \"customsQuantities\": [\n {\n \"value\": 0.8,\n \"unitOfMeasure\": \"Kg\"\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://dutycollection.safepackage.com/api/v1/shipments","description":"API that processes complete shipments with multiple containers, packages, and items in a single operation.
\nThis endpoint creates a complete shipment workflow by:
\nCreating all packages and their items
\nCreating containers with entry route information
\nAutomatically associating packages with their containers
\nCalculating duties and taxes for all items
\ncontainers (array, required): Collection of containers with their packages
\nMinimum: 1 container required
\nMaximum: No system limit (practical limit ~100 containers per request)
\ntrackingReference (string, required): Unique container identifier
\nFormat: Alphanumeric, max 50 characters
\nExample: CONT001-AA1234 (often includes flight/vessel reference)
Must be unique across ALL containers in the shipment
\nBest Practice: Include transport reference for easy identification
\nentryRoute (object, required): Transportation and entry information
\npackages (array, required): Packages contained within this container
\nMinimum: 1 package per container
\nEach container must have at least one package
\nPackage tracking references must be unique across entire shipment
\nflightOrTripNumber (string, required): Transportation identifier
\nAir Transport: Flight number (e.g., AA1234, DL53, UA567, BA890)
Vessel Transport: Voyage/booking number (e.g., MAEU-123, COSCO-456)
Ground Transport: Trip/route number (e.g., FDX-456, UPS-789)
Format: Alphanumeric, max 50 characters
\nUsed for tracking and customs documentation
\ntransportType (enum, required): Mode of transportation
\nValues: Air, Vessel, Ground
Case-sensitive - must match exactly
\nDetermines applicable customs regulations and processing procedures
\ncarrierCode (string, required): Transportation company identifier
\nAirlines: IATA codes preferred (AA, UA, DL, BA)
Shipping Lines: Standard codes (MSC, MAEU, COSCO)
Ground: Carrier identifiers (FEDX, UPS, DHL)
Format: Alphanumeric, max 10 characters
\nUsed for carrier accountability and routing
\narrivalPortCode (string, required): CBP port of entry
\nFormat: Standard CBP district/port codes
\nExample: 4701 for specific port locations
Critical: Must be valid CBP-recognized port code
\nUsed for duty collection jurisdiction and compliance reporting
\nMax length: 10 characters
\nentryTimestamp (string, required): Scheduled arrival date/time
\nFormat: ISO 8601 with timezone (YYYY-MM-DDTHH:mm:ssZ)
Example: 2024-01-15T10:30:00Z (UTC timezone recommended)
Important: Should align with actual transportation schedules
\nUsed for entry processing windows and compliance deadlines
\ntrackingReference (string, required): Unique package identifier
\nFormat: Alphanumeric, max 50 characters
\nExample: US123456789US, CN987654321CN (format: XX123456789XX where XX is country code)
Must be unique across ALL packages in the entire shipment
\nBest Practice: Use standardized format for international tracking
\nitems (array, required): Items contained within this package
\nMinimum: 1 item per package
\nNo maximum limit (practical limit ~50 items per package)
\npgaData (array, optional for now): PGA (Partner Government Agency) data elements for the item, driven by the item's HTS code
\nEach entry carries a type (string enum) and a value (string, max 1000 characters)
\nA type may appear at most once per item
\ntype values: IntendedUse, IntendedUseCode, ProductCode, CountryOfProduction, TradeBrandName, ProductSpecificDescription, ManufacturerFei, ImporterOfRecordFei, PointOfContact, ShipperFei, DeliveredToPartyFei, PackagingLevels, ProductId, CitationCodes, ManufactureDate, ManufacturePlace, ProductTestDate, TestingLaboratory, CountryOfHarvest, ScientificNameGenus, ScientificNameSpecies, CommonName, PermitNumber, ManufacturerId, TscaCertification
Which types are needed depends on the PGA indicators of the item's HTS code — e.g. FDA-flagged codes (food contact, cosmetics) call for IntendedUse, ProductCode, CountryOfProduction, TradeBrandName, ProductSpecificDescription and PackagingLevels
notForMedicalUse (boolean, optional for now, defaults to false): attests the product is not intended for medical use
trueOnce the Entry Type 13 requirement is enforced for your account, packages failing the PGA rules are rejected with error codes V_PgaRequiredInformationMissing, V_HtsCodeNotApprovedForShipping or V_NotForMedicalUseAttestationRequired
{\n \"message\": \"Shipment created successfully\",\n \"packageCount\": 4,\n \"containerCount\": 2,\n \"packages\": [\n {\n \"id\": \"uuid\",\n \"trackingReference\": \"US123456789US\",\n \"totalDeclaredValue\": 41.49,\n \"totalDutiesOwed\": 4.15,\n \"items\": [...],\n \"createdAtUtc\": \"2024-01-15T10:35:00Z\"\n }\n ],\n \"containers\": [\n {\n \"id\": \"uuid\",\n \"trackingReference\": \"CONT001-AA1234\",\n \"entryRoute\": {...},\n \"packages\": [...],\n \"createdAtUtc\": \"2024-01-15T10:35:00Z\"\n }\n ]\n}\n\nSupports complex shipping scenarios:
\nMixed Transport Types: Air + Vessel + Ground in same shipment
\nMultiple Carriers: Different airlines/shipping companies
\nMultiple Arrival Times: Staggered arrivals
\nMultiple Ports: Different entry points
\n✅ Duty Calculation: Automatic based on origin country and value
\n✅ Tariff Application: Current trade policy enforcement
\n✅ Manifest Generation: CBP-compliant documentation
\n✅ Reference Validation: Ensures all references are unique
\n✅ Business Rules: Enforces regulatory compliance
\nContainer Uniqueness: All container tracking references must be unique within shipment
\nPackage Uniqueness: All package tracking references must be globally unique within shipment
\nPackage Distribution: Each container must have at least one package
\nItem Requirements: Each package must have at least one item
\nValue Validation: All declared values must be positive numbers
\nCountry Codes: All origin countries must be valid ISO codes
\nTransport Consistency: Transport type must align with carrier and flight/trip numbers
\nEfficiency: Process entire shipments in single API call
\nConsistency: Ensures data integrity across packages and containers
\nCompliance: Automatic CBP manifest generation and duty calculation
\nTraceability: Complete audit trail from item to container to shipment
\nFlexibility: Supports all transport modes and complex routing
\nAir Cargo Processing: Multiple flights with various packages
\nInternational Flight Arrivals: Processing packages from commercial airlines
\nCross-Border E-commerce: Bulk processing of small packages via air
\nAir Freight Consolidation: Multiple packages per flight
\nExpress Air Delivery: Consolidated packages from international hubs
\nTrade Compliance: Ensure proper duty collection and documentation
\nRecommended: Max 50 containers per request for optimal performance
\nPackage Limit: Max 100 packages per container for reasonable response times
\nItem Limit: Max 50 items per package for efficient processing
\nTimeout: Large requests may take 30-60 seconds to process
\nRetry Logic: Implement exponential backoff for timeout scenarios
\nAll API errors are returned as an array of error objects with the following structure:
\n [\n {\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human-readable error message\"\n }\n ]\n\nAuthentication Errors (AUTH-*)
\nApplication Errors (APP-*)
\nResource Not Found Errors (RM-*)
\nValidation Errors (V-*)
\nDomain/Business Logic Errors (D-*)
\n[
{
\"code\": \"RM-ClientNotFound\",
\"message\": \"Client not found\"
}
]
[
{
\"code\": \"V-InvalidEmail\",
\"message\": \"Invalid email format\"
},
{
\"code\": \"V-ValueEmpty\",
\"message\": \"Value cannot be empty\"
}
]
Complete shipment processing combining packages, containers, and manifest generation in a single operation.
\n","_postman_id":"664668dc-b7c8-485d-a4b2-3b787a8f95db"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["// International Mail Duty Collection API - Auto Token Management","// This script automatically handles JWT token refresh for seamless API testing","","const tokenUrl = pm.environment.get('token_url') || pm.globals.get('token_url');","const clientId = pm.environment.get('client_id') || pm.globals.get('client_id');","const clientSecret = pm.environment.get('client_secret') || pm.globals.get('client_secret');","","// Skip token refresh for development environment","const baseUrl = pm.environment.get('base_url') || pm.globals.get('base_url');","if (baseUrl && baseUrl.includes('localhost')) {"," console.log('Development environment detected - skipping authentication');"," return;","}","","// Check if we need to refresh the token","const currentToken = pm.environment.get('access_token') || pm.globals.get('access_token');","const tokenExpiry = pm.environment.get('token_expiry') || pm.globals.get('token_expiry');","","const now = new Date().getTime();","const expiryTime = tokenExpiry ? parseInt(tokenExpiry) : 0;","","// Refresh token if expired or not present","if (!currentToken || now >= expiryTime) {"," if (!tokenUrl || !clientId || !clientSecret) {"," console.warn('Token credentials not configured. Set token_url, client_id, and client_secret in environment variables.');"," return;"," }"," "," console.log('Refreshing access token...');"," "," pm.sendRequest({"," url: tokenUrl,"," method: 'POST',"," header: {"," 'Content-Type': 'application/x-www-form-urlencoded'"," },"," body: {"," mode: 'urlencoded',"," urlencoded: ["," { key: 'grant_type', value: 'client_credentials' },"," { key: 'client_id', value: clientId },"," { key: 'client_secret', value: clientSecret }"," ]"," }"," }, (err, res) => {"," if (err) {"," console.error('Token refresh failed:', err);"," return;"," }"," "," if (res.code === 200) {"," const responseJson = res.json();"," const newToken = responseJson.access_token;"," const expiresIn = responseJson.expires_in || 3600;"," const newExpiry = new Date().getTime() + (expiresIn * 1000) - 60000; // 1 min buffer"," "," pm.environment.set('access_token', newToken);"," pm.environment.set('token_expiry', newExpiry.toString());"," "," console.log('Token refreshed successfully');"," } else {"," console.error('Token refresh failed with status:', res.code);"," console.error('Response:', res.text());"," }"," });","} else {"," console.log('Token is still valid');","}"],"id":"f6a6f360-b772-4f38-b7cb-71ad77d77a4f"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"191ba1e0-dce4-4f52-98bc-26338e74b9e2"}}],"variable":[{"key":"base_url","value":"https://dutycollection.safepackage.com","description":"API Base URL - Production endpoint"},{"key":"token_url","value":"https://auth.dutycollection.safepackage.com/protocol/openid-connect/token","description":"OAuth2 token endpoint - Update with your actual realm"},{"key":"client_id","value":"","description":"OAuth2 client ID for API access"},{"key":"client_secret","value":"","description":"OAuth2 client secret - Keep secure!"},{"key":"access_token","value":"","description":"JWT access token - Auto-managed by pre-request script"},{"key":"token_expiry","value":"","description":"Token expiry timestamp - Auto-managed"}]}