### How this function works You can use this function to calculate real-time shipping rates across global carriers using [ShipEngine](https://www.shipengine.com/). > Rate estimates are not exact quotes as they may not include things like insurance amount, fuel surcharges, customs charges, or other carrier fees. ### Prerequisites - You must have previous knowledge of **ShipEngine**. - You must have previous knowledge of **Cloud Firestore**. ### Function details To install this function, add the required information to the form with the following parameters: - **Document Path**: The document path that you'd like this function to listen to. A placeholder should be used for the document ID (e.g., `/collection/{docId}`). - **SHIPENGINE_API_KEY**: The ShipEngine API Key. - **RATES_FIELD_NAME**: The name of the document field where the address validation results will be stored (e.g., 'rates'). - **CARRIERS_IDS**: An array of carrier IDs from your ShipEngine account. > All fields are required. ### Using this function Once the function is installed, you can start adding documents to the collection that would trigger this function. The document must have either a `shipmentId` obtained from ShipEngine (see [Create a Shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/)) or a `shipment` object as described in [Estimate a Rate](https://www.shipengine.com/docs/rates/estimate/). Use camel case for properties (e.g., `serviceCodes` instead of `service_codes`). Additionally, it may contain a field named `rateOptions` to provide other options for calculating rates. See the examples section. Here is an example of calculated rates (assuming that we have set the value of `RATES_FIELD_NAME` to "rates"): ```json { "rates": [{ "rateId": "se-1234", "rateType": "shipment", "carrierId": "se-1179703", "shippingAmount": { "currency": "usd", "amount": 0.53 }, "insuranceAmount": { "currency": "usd", "amount": 0 }, "confirmationAmount": { "currency": "usd", "amount": 0 }, "otherAmount": { "currency": "usd", "amount": 0 }, "taxAmount": null, "zone": 7, "packageType": "letter", "deliveryDays": 4, "guaranteedService": false, "estimatedDeliveryDate": "2021-12-11T00:00:00Z", "carrierDeliveryDays": "4", "shipDate": "2021-12-07T00:00:00Z", "negotiatedRate": false, "serviceType": "USPS First Class Mail", "serviceCode": "usps_first_class_mail", "trackable": false, "carrierCode": "stamps_com", "carrierNickname": "ShipEngine Test Account - Stamps.com", "carrierFriendlyName": "Stamps.com", "validationStatus": "valid", "warningMessages": [], "errorMessages": [] }] } ``` > A full response object can be found in *Example Response* from the [Calculate Shipping Costs](https://www.shipengine.com/docs/rates/) section in ShipEngine API docs. ### Usage examples Here are some examples of documents to trigger this function. #### Example 1: Calculating rates using shipment ID ```javascript { shipmentId: 'se-123', } ``` #### Example 2: Calculating rates using shipment details ```javascript { shipment: { shipTo: { name: 'Sherlock Holmes', addressLine1: '221B Baker St', cityLocality: 'London', stateProvince: 'Westminster', postalCode: 'NW1 6XE', countryCode: 'GB', }, shipFrom: { companyName: 'Scotland Yard', name: 'Dr. John H. Watson', phone: '111-111-111111', addressLine1: '4 Whitehall Place St', cityLocality: 'London', stateProvince: 'Westminster', postalCode: 'NW1 6XE', countryCode: 'GB', }, packages: [{ weight: { value: 5.0, unit: 'ounce', }, }], }, } ``` #### Example 3: Calculating rates using package types ```javascript { shipmentId: 'se-123', rateOptions: { serviceCodes: [], packageTypes: [ 'flat_rate_envelope', 'medium_flat_rate_box', ], }, }; ``` #### Example 4: Calculating rates using service codes ```javascript { shipmentId: 'se-123', rateOptions: { serviceCodes: [ 'usps_first_class_mail', 'usps_priority_mail', 'ups_next_day_air_early_am' ], packageTypes: [], } } ``` #### Example 5: Calculating rates using both service codes and package types ```javascript { shipmentId: 'se-123', rateOptions: { serviceCodes: [ 'usps_first_class_mail', 'usps_priority_mail', 'ups_next_day_air_early_am' ], packageTypes: [ 'flat_rate_envelope', 'medium_flat_rate_box', ], }, } ``` ### Resources - [Calculate Shipping Costs](https://www.shipengine.com/docs/rates/) - [ShipEngine API Management page](https://app.shipengine.com/#/portal/apimanagement) - [ShipEngine documentation](https://www.shipengine.com/docs/getting-started/)