### How this function works You can use this function to create domestic US or international shipping labels with [ShipEngine](https://www.shipengine.com/). Shipping labels are created based on the contents of a document written to a specified Cloud Firestore collection. ### 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. - **SHIPPING_LABEL_FIELD_NAME**: The name of the document field where the shipping label will be stored (e.g., 'shippingLabel'). > 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 `shipment` object as described in [Create a Shipping Label](https://www.shipengine.com/docs/labels/create-a-label/) or a `rateId` (see [Create a Label from a Rate](https://www.shipengine.com/docs/labels/create-from-rate/)). Use camel case for properties (e.g., `serviceCodes` instead of `service_codes`). Here is an example of a purchased label (assuming that we have set the value of `SHIPPING_LABEL_FIELD_NAME` to "shippingLabel"): ```json { "shippingLabel": { "labelId": "se-7764944", "status": "completed", "shipmentId": "se-21748537", "shipDate": "2020-04-17T00:00:00Z", "createdAt": "2020-04-17T16:22:20.9879673Z", "shipmentCost": { "currency": "usd", "amount": 10.19 }, "insuranceCost": { "currency": "usd", "amount": 0.0 }, "chargeEvent": "carrier_default", "trackingNumber": "9405511899564088683810", "isReturnLabel": false, "rmaNumber": null, "isInternational": false, "batchId": "", "carrierId": "se-169349", "serviceCode": "usps_priority_mail", "packageCode": "package", "voided": false, "voidedAt": null, "labelFormat": "pdf", "labelLayout": "4x6", "trackable": true, "labelImage_id": null, "carrierCode": "stamps_com", "trackingStatus": "in_transit", "labelDownload": { "pdf": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf", "png": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.png", "zpl": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.zpl", "href": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf" }, "formDownload": null, "insuranceClaim": null, "packages": [ { "packageCode": "package", "weight": { "value": 20.0, "unit": "ounce" }, "dimensions": { "unit": "inch", "length": 0.0, "width": 0.0, "height": 0.0 }, "insuredValue": { "currency": "usd", "amount": 0.0 }, "trackingNumber": "9405511899564088683810", "labelMessages": { "reference1": null, "reference2": null, "reference3": null }, "externalPackageId": null } ] } } ``` ### Usage examples Here are some examples of documents to trigger this function. #### Example 1: Creating a shipping label from a shipment ```javascript { shipment: { carrierId: 'se-423887', serviceCode: 'usps_media_mail', 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 2: Creating a shipping label from a rate ```javascript { rateId: 'se-123', } ``` ### Resources - [Create a Shipping Label](https://www.shipengine.com/docs/labels/create-a-label/) - [Label Formats and Sizes](https://www.shipengine.com/docs/labels/formats/) - [ShipEngine API Management page](https://app.shipengine.com/#/portal/apimanagement) - [ShipEngine documentation](https://www.shipengine.com/docs/getting-started/)