import {z} from 'zod' export type LabelDownloadType = 'url' | 'inline'; export type GetApiV2LabelsExternalShipmentIdExternalShipmentIdArgs = {label_download_type?: LabelDownloadType | undefined}; export type GetApiV2LabelsExternalShipmentIdExternalShipmentIdOptions = {baseUrl?: string | undefined, apiKeys?: string | undefined, fetch?: typeof fetch | undefined}; export const seId = z.string().min(1).max(25); export const labelStatus = z.enum(["processing", "completed", "error", "voided"]); export const serviceCode = z.string(); export const currency = z.string(); export const monetaryValue = z.object({currency: currency, amount: z.number().gte(0)}); export const orderSourceName = z.enum(["amazon_ca", "amazon_us", "brightpearl", "channel_advisor", "cratejoy", "ebay", "etsy", "jane", "groupon_goods", "magento", "paypal", "seller_active", "shopify", "stitch_labs", "squarespace", "three_dcart", "tophatter", "walmart", "woo_commerce", "volusion"]); export const weightUnit = z.enum(["pound", "ounce", "gram", "kilogram"]); export const weight = z.object({value: z.number().gt(0), unit: weightUnit}); export const shipmentItem = z.object({name: z.string().optional(), sales_order_id: z.string().nullable().optional(), sales_order_item_id: z.string().nullable().optional(), quantity: z.number().int().gte(0).optional(), sku: z.string().nullable().optional(), bundle_sku: z.string().nullable().optional(), external_order_id: z.string().nullable().optional(), external_order_item_id: z.string().nullable().optional(), asin: z.string().min(10).max(10).nullable().optional(), order_source_code: orderSourceName.optional(), item_id: z.string().nullable().optional(), allocation_status: z.string().nullable().optional(), image_url: z.string().nullable().optional(), weight: weight.optional(), unit_price: z.number().gte(0).nullable().optional(), tax_amount: z.number().gte(0).nullable().optional(), shipping_amount: z.number().gte(0).nullable().optional(), inventory_location: z.string().nullable().optional(), options: z.array(z.object({name: z.string().optional(), value: z.string().optional()})).optional(), product_id: z.string().nullable().optional(), fullfilment_sku: z.string().nullable().optional(), upc: z.string().nullable().optional()}); export const taxableEntityType = z.enum(["shipper", "recipient", "ior"]); export const identifierType = z.enum(["vat", "eori", "ssn", "ein", "tin", "ioss", "pan", "voec", "pccc", "oss", "passport", "abn", "ukims"]); export const taxIdentifier = z.object({taxable_entity_type: taxableEntityType, identifier_type: identifierType, issuing_authority: z.string(), value: z.string()}); export const date = z.string(); export const dateTime = z.string(); export const shipmentStatus = z.enum(["pending", "processing", "label_purchased", "cancelled"]); export const postalCode = z.string().min(1); export const countryCode = z.string().min(2).max(2); export const addressResidentialIndicator = z.enum(["unknown", "yes", "no"]); export const shippingAddressTo = z.object({name: z.string().min(1), phone: z.string().min(1), email: z.string().nullable().optional(), company_name: z.string().min(1).nullable().optional(), address_line1: z.string().min(1), address_line2: z.string().min(1).nullable().optional(), address_line3: z.string().min(1).nullable().optional(), city_locality: z.string().min(1), state_province: z.string().min(1), postal_code: postalCode, country_code: countryCode, address_residential_indicator: addressResidentialIndicator, instructions: z.string().min(1).nullable().optional(), geolocation: z.array(z.object({type: z.literal("what3words").optional(), value: z.string().optional()})).optional()}); export const shippingAddress = z.object({name: z.string().min(1), phone: z.string().min(1), email: z.string().nullable().optional(), company_name: z.string().min(1).nullable().optional(), address_line1: z.string().min(1), address_line2: z.string().min(1).nullable().optional(), address_line3: z.string().min(1).nullable().optional(), city_locality: z.string().min(1), state_province: z.string().min(1), postal_code: postalCode, country_code: countryCode, address_residential_indicator: addressResidentialIndicator, instructions: z.string().min(1).nullable().optional(), geolocation: z.array(z.object({type: z.literal("what3words").optional(), value: z.string().optional()})).optional()}); export const deliveryConfirmation = z.enum(["none", "delivery", "signature", "adult_signature", "adult_signature_restricted_delivery", "direct_signature", "delivery_mailed", "verbal_confirmation", "delivery_code", "age_verification_16_plus"]); export const packageContents = z.enum(["merchandise", "documents", "gift", "returned_goods", "sample", "e_commerce_goods", "commercial_sale_of_goods_b2b", "other"]); export const nonDelivery = z.enum(["return_to_sender", "treat_as_abandoned"]); export const termsOfTradeCode = z.enum(["exw", "fca", "cpt", "cip", "dpu", "dap", "ddp", "fas", "fob", "cfr", "cif", "ddu", "daf", "deq", "des"]); export const estimatedImportCharges = z.object({taxes: monetaryValue.optional(), duties: monetaryValue.optional()}); export const invoiceAdditionalDetails = z.object({freight_charge: monetaryValue.optional(), insurance_charge: monetaryValue.optional(), discount: monetaryValue.optional(), estimated_import_charges: estimatedImportCharges.optional(), other_charge: monetaryValue.optional(), other_charge_description: z.string().optional()}); export const importerOfRecords = z.object({name: z.string().min(1), phone: z.string().min(1).optional(), email: z.string().nullable().optional(), company_name: z.string().min(1).nullable().optional(), address_line1: z.string().min(1), address_line2: z.string().min(1).nullable().optional(), address_line3: z.string().min(1).nullable().optional(), city_locality: z.string().min(1), state_province: z.string().min(1).optional(), postal_code: postalCode, country_code: countryCode}); export const internationalShipmentOptions = z.object({contents: packageContents, contents_explanation: z.string().optional(), non_delivery: nonDelivery, terms_of_trade_code: termsOfTradeCode.optional(), declaration: z.string().optional(), pending_documents: z.boolean().optional(), invoice_additional_details: invoiceAdditionalDetails.optional(), importer_of_record: importerOfRecords.optional(), customs_items: z.array(z.object({customs_item_id: seId, description: z.string().max(100).nullable().optional(), quantity: z.number().int().gte(0).optional(), value: z.number().gte(0).optional(), value_currency: z.string().optional(), weight: weight.optional(), harmonized_tariff_code: z.string().nullable().optional(), country_of_origin: countryCode.nullable().optional(), unit_of_measure: z.string().nullable().optional(), sku: z.string().nullable().optional(), sku_description: z.string().nullable().optional()})).optional()}); export const billToParty = z.enum(["recipient", "third_party"]); export const originType = z.enum(["pickup", "drop_off"]); export const collectOnDeliveryPaymentType = z.enum(["any", "cash", "cash_equivalent", "none"]); export const regulatedContentType = z.enum(["day_old_poultry", "other_live_animal"]); export const advancedShipmentOptions = z.object({bill_to_account: z.string().nullable().optional(), bill_to_country_code: countryCode.nullable().optional(), bill_to_party: billToParty.nullable().optional(), bill_to_postal_code: z.string().nullable().optional(), contains_alcohol: z.boolean().optional(), delivered_duty_paid: z.boolean().optional(), duties_and_taxes_payment: z.enum(["guaranteed", "carrier_billed", "null"]).nullable().optional(), dry_ice: z.boolean().optional(), dry_ice_weight: weight.nullable().optional(), non_machinable: z.boolean().optional(), saturday_delivery: z.boolean().optional(), fedex_freight: z.object({shipper_load_and_count: z.string().optional(), booking_confirmation: z.string().optional()}).optional(), use_ups_ground_freight_pricing: z.boolean().nullable().optional(), freight_class: z.string().nullable().optional(), custom_field1: z.string().max(100).nullable().optional(), custom_field2: z.string().max(100).nullable().optional(), custom_field3: z.string().max(100).nullable().optional(), origin_type: originType.nullable().optional(), additional_handling: z.boolean().nullable().optional(), shipper_release: z.boolean().nullable().optional(), collect_on_delivery: z.object({payment_type: collectOnDeliveryPaymentType.optional(), payment_amount: z.object({currency: currency.optional(), amount: z.number().gte(0).optional()}).optional()}).optional(), third_party_consignee: z.boolean().optional(), dangerous_goods: z.boolean().optional(), dangerous_goods_contact: z.object({name: z.string().optional(), phone: z.string().optional()}).optional(), movement_indicator: z.enum(["c2c", "b2c", "c2b", "b2b"]).nullable().optional(), windsor_framework_details: z.object({movement_indicator: z.enum(["c2c", "b2c", "c2b", "b2b"]).optional(), not_at_risk: z.boolean().optional()}).optional(), ancillary_endorsements_option: z.string().nullable().optional(), return_pickup_attempts: z.number().int().nullable().optional(), own_document_upload: z.boolean().optional(), limited_quantity: z.boolean().optional(), event_notification: z.boolean().optional(), fragile: z.boolean().optional(), delivery_as_addressed: z.boolean().optional(), return_after_first_attempt: z.boolean().optional(), regulated_content_type: regulatedContentType.nullable().optional(), netstamps_options: z.object({row: z.number().int().optional(), column: z.number().int().optional()}).optional(), suppress_carrier_generated_documents: z.array(z.literal("commercial_invoice")).optional(), transparency_codes: z.array(z.object({order_item_id: z.string(), codes: z.array(z.string())})).optional()}); export const insuranceProvider = z.enum(["none", "shipsurance", "parcelguard", "x_cover", "carrier", "third_party"]); export const tag = z.object({name: z.string().min(1)}); export const packageCode = z.string().min(1).max(50); export const dimensionUnit = z.enum(["inch", "centimeter"]); export const dimensions = z.object({unit: dimensionUnit, length: z.number().gte(0), width: z.number().gte(0), height: z.number().gte(0)}); export const labelMessages = z.object({reference1: z.string().nullable(), reference2: z.string().nullable(), reference3: z.string().nullable()}); export const dangerousAmount = z.object({amount: z.number().gte(0).optional(), unit: z.string().nullable().optional()}); export const dangerousGoods = z.object({id_number: z.string().nullable().optional(), shipping_name: z.string().nullable().optional(), technical_name: z.string().nullable().optional(), product_class: z.string().nullable().optional(), product_class_subsidiary: z.string().nullable().optional(), packaging_group: z.enum(["i", "ii", "iii"]).optional(), dangerous_amount: dangerousAmount.optional(), quantity: z.number().int().gte(0).optional(), packaging_instruction: z.string().nullable().optional(), packaging_instruction_section: z.enum(["section_1", "section_2", "section_1a", "section_1b"]).optional(), packaging_type: z.string().nullable().optional(), transport_mean: z.enum(["ground", "water", "cargo_aircraft_only", "passenger_aircraft"]).optional(), transport_category: z.string().nullable().optional(), regulation_authority: z.string().nullable().optional(), regulation_level: z.enum(["lightly_regulated", "fully_regulated", "limited_quantities", "excepted_quantity"]).optional(), radioactive: z.boolean().nullable().optional(), reportable_quantity: z.boolean().nullable().optional(), tunnel_code: z.string().nullable().optional(), additional_description: z.string().nullable().optional()}); export const manufacturerProductIdentifierType = z.enum(["undefined", "gtin", "ean", "isbn", "upc", "mpn", "sku"]); export const cpscCertificate = z.object({certifier_id: z.string().max(50).optional(), certificate_version_id: z.string().max(50).optional()}); export const eudr = z.object({dds_reference_number: z.string().max(20).nullable().optional(), taric_document_code: z.string().max(4).nullable().optional()}); export const regulations = z.object({eudr: eudr.nullable().optional()}); export const package = z.object({shipment_package_id: seId.optional(), package_id: seId.optional(), package_code: packageCode.optional(), package_name: z.string().optional(), weight: weight, dimensions: dimensions.optional(), insured_value: monetaryValue.optional(), label_messages: labelMessages.optional(), external_package_id: z.string().min(1).optional(), content_description: z.string().min(1).max(35).nullable().optional(), products: z.array(z.object({description: z.string().max(100).nullable().optional(), quantity: z.number().int().gte(0).optional(), value: monetaryValue.optional(), weight: weight.optional(), harmonized_tariff_code: z.string().nullable().optional(), country_of_origin: countryCode.nullable().optional(), unit_of_measure: z.string().nullable().optional(), sku: z.string().nullable().optional(), sku_description: z.string().nullable().optional(), mid_code: z.string().nullable().optional(), product_url: z.string().nullable().optional(), vat_rate: z.number().nullable().optional(), dangerous_goods: z.array(dangerousGoods).optional(), manufacturer_product_id_type: manufacturerProductIdentifierType.nullable().optional(), manufacturer_product_id: z.string().nullable().optional(), manufacturer_ns_product_id: z.string().nullable().optional(), cpsc_certificates: z.array(cpscCertificate).nullable().optional(), cpsc_disclaim: z.object({disclaim_code: z.enum(["A", "B"]), intended_use_code: z.string().max(16), intended_use_description: z.string().max(100).nullable().optional()}).nullable().optional(), regulations: regulations.nullable().optional()})).optional()}); export const weigth = z.object({value: z.number().gt(0), unit: weightUnit}); export const shipment = z.object({shipment_id: seId, carrier_id: seId.nullable().optional(), service_code: serviceCode.nullable().optional(), requested_shipment_service: z.string().nullable().optional(), external_order_id: z.string().nullable().optional(), hold_until_date: z.string().nullable().optional(), ship_by_date: z.string().nullable().optional(), deliver_by_date: z.string().nullable().optional(), retail_rate: monetaryValue.nullable().optional(), store_id: seId.optional(), items: z.array(shipmentItem).optional(), notes_from_buyer: z.string().nullable().optional(), notes_to_buyer: z.string().nullable().optional(), notes_for_gift: z.string().nullable().optional(), internal_notes: z.string().nullable().optional(), is_gift: z.boolean().optional(), assigned_user: z.string().nullable().optional(), amount_paid: monetaryValue.optional(), shipping_paid: monetaryValue.optional(), tax_paid: monetaryValue.optional(), zone: z.number().int().gte(0).nullable().optional(), display_scheme: z.string().nullable().optional(), tax_identifiers: z.array(taxIdentifier).nullable().optional(), external_shipment_id: z.string().max(50).nullable().optional(), shipment_number: z.string().max(50).nullable().optional(), ship_date: date.nullable().optional(), created_at: dateTime, modified_at: dateTime, shipment_status: shipmentStatus, ship_to: shippingAddressTo, ship_from: shippingAddress, warehouse_id: seId.nullable().optional(), return_to: shippingAddress, is_return: z.boolean().nullable().optional(), confirmation: deliveryConfirmation.optional(), customs: internationalShipmentOptions.nullable().optional(), advanced_options: advancedShipmentOptions.optional(), insurance_provider: insuranceProvider, tags: z.array(tag), order_source_code: orderSourceName.optional(), packages: z.array(package), total_weight: weigth, batch_ids: z.array(seId), comparison_rate_type: z.string().nullable().optional(), sales_order_ids: z.array(z.string()).optional()}); export const deliveryPrediction = z.object({delivery_date: z.string().nullable().optional(), confidence_level: z.enum(["high", "low"]).optional()}); export const labelChargeEvent = z.enum(["carrier_default", "on_creation", "on_carrier_acceptance"]); export const validateAddress = z.enum(["no_validation", "validate_only", "validate_and_clean"]); export const voidType = z.enum(["refund_assist", "manual"]); export const refundStatus = z.enum(["request_scheduled", "pending", "approved", "rejected", "excluded"]); export const refundDetails = z.object({refund_status: refundStatus.optional(), request_date: dateTime.optional(), amount_paid: monetaryValue.nullable().optional(), amount_requested: monetaryValue.nullable().optional(), amount_approved: monetaryValue.nullable().optional(), amount_credited: monetaryValue.nullable().optional()}); export const labelDownloadType = z.enum(["url", "inline"]); export const labelFormat = z.enum(["pdf", "png", "zpl"]); export const displayScheme = z.enum(["label", "paperless", "label_and_paperless"]); export const labelLayout = z.enum(["4x6", "letter"]); export const imageId = z.string().min(4); export const carrierCode = z.string(); export const trackingStatus = z.enum(["unknown", "in_transit", "error", "delivered"]); export const url = z.string().min(1); export const labelDownload = z.object({href: url.optional(), pdf: url.optional(), png: url.optional(), zpl: url.optional()}); export const link = z.object({href: url.optional(), type: z.string().min(1).optional()}); export const optionalLink = z.object({href: url.optional(), type: z.string().min(1).optional()}); export const paperlessDownload = z.object({href: url.optional(), instructions: z.string().nullable().optional(), handoff_code: z.string().nullable().optional()}); export const trackingNumber = z.string().min(1); export const alternativeIdentifier = z.object({type: z.string().min(1).optional(), value: z.string().min(1).optional()}); export const rateDetail = z.object({rate_detail_type: z.string().optional(), carrier_description: z.string().nullable().optional(), carrier_billing_code: z.string().nullable().optional(), carrier_memo: z.string().nullable().optional(), amount: monetaryValue.optional(), billing_source: z.string().optional()}); export const getLabelByExternalShipmentIdResponseBody = z.object({label_id: seId.optional(), status: labelStatus.optional(), shipment_id: seId.optional(), external_shipment_id: z.string().max(50).nullable().optional(), external_order_id: z.string().nullable().optional(), shipment: shipment.optional(), ship_date: date.optional(), delivery_prediction: deliveryPrediction.optional(), created_at: dateTime.optional(), shipment_cost: monetaryValue.optional(), insurance_cost: monetaryValue.optional(), requested_comparison_amount: monetaryValue.optional(), tracking_number: z.string().min(1).optional(), is_return_label: z.boolean().optional(), rma_number: z.string().nullable().optional(), is_international: z.boolean().optional(), batch_id: seId.optional(), carrier_id: seId.optional(), charge_event: labelChargeEvent.optional(), outbound_label_id: seId.optional(), service_code: serviceCode.optional(), test_label: z.boolean().optional(), package_code: packageCode.optional(), validate_address: validateAddress.optional(), voided: z.boolean().optional(), voided_at: dateTime.nullable().optional(), void_type: voidType.nullable().optional(), refund_details: refundDetails.nullable().optional(), label_download_type: labelDownloadType.optional(), label_format: labelFormat.optional(), display_scheme: displayScheme.optional(), label_layout: labelLayout.optional(), trackable: z.boolean().optional(), label_image_id: imageId.nullable().optional(), carrier_code: carrierCode.optional(), confirmation: deliveryConfirmation.optional(), tracking_status: trackingStatus.optional(), label_download: labelDownload.optional(), form_download: link.nullable().optional(), qr_code_download: optionalLink.nullable().optional(), paperless_download: paperlessDownload.nullable().optional(), insurance_claim: link.nullable().optional(), packages: z.array(z.object({package_id: z.number().int().optional(), package_code: packageCode.optional(), weight: weight, dimensions: dimensions.optional(), insured_value: monetaryValue.optional(), tracking_number: trackingNumber.optional(), label_download: labelDownload.optional(), form_download: optionalLink.optional(), qr_code_download: optionalLink.optional(), paperless_download: paperlessDownload.optional(), label_messages: labelMessages.optional(), external_package_id: z.string().min(1).optional(), content_description: z.string().min(1).max(35).nullable().optional(), sequence: z.number().int().optional(), has_label_documents: z.boolean().optional(), has_form_documents: z.boolean().optional(), has_qr_code_documents: z.boolean().optional(), has_paperless_label_documents: z.boolean().optional(), alternative_identifiers: z.array(alternativeIdentifier).nullable().optional()})).optional(), alternative_identifiers: z.array(alternativeIdentifier).nullable().optional(), rate_details: z.array(rateDetail).optional(), tracking_url: z.string().nullable().optional(), ship_to: shippingAddressTo.optional()}); export const validateResponse = async ( schema: { readonly '~standard': { readonly validate: (value: unknown) => ({ readonly value: Output; readonly issues?: undefined } | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray | undefined }> }) | Promise<{ readonly value: Output; readonly issues?: undefined } | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray | undefined }> }> } }, value: unknown ): Promise => { const result = await schema['~standard'].validate(value) if (result.issues !== undefined) { const detail = result.issues .map(({ message, path }) => path?.length ? `${path.map((segment) => String(typeof segment === 'object' ? segment.key : segment)).join('.')}: ${message}` : message ) .join('; ') throw new Error(`Response does not match the schema: ${detail}`, { cause: { issues: result.issues } }) } return result.value }; /** * Get label by external shipment ID * * GET /v2/labels/external_shipment_id/{external_shipment_id} */ export const getApiV2LabelsExternalShipmentIdExternalShipmentId = async (args: GetApiV2LabelsExternalShipmentIdExternalShipmentIdArgs, options?: GetApiV2LabelsExternalShipmentIdExternalShipmentIdOptions) => { const {baseUrl = "https://api.shipstation.com", fetch: fetchFn = fetch, apiKeys} = options ?? {} const query = new URLSearchParams() const headers = new Headers() headers.set('accept', "application/json") if (args.label_download_type != null) query.append("label_download_type", String(args.label_download_type)) if (apiKeys !== undefined) headers.set("api-key", apiKeys) const url = `${baseUrl.replace(/\/+$/, '')}/v2/labels/external_shipment_id/${encodeURIComponent(String(args.external_shipment_id))}${query.size > 0 ? `?${query}` : ''}` const res = await fetchFn(url, {method: "GET", headers}) if (!res.ok) throw new Error(`Request failed with status ${res.status}`, {cause: {status: res.status, body: await res.text()}}) return validateResponse(getLabelByExternalShipmentIdResponseBody, await res.json()) };