API Guide
Note: this article refers how we interact with the Stripe API, for info on getting your EasyPost API key, see Connect Your EasyPost API key to Parcelcraft.
Parcelcraft doens't require any software programming skills to use, but for those who have a need to interact with Parcelcraft programmically, we have a variety of ways to interact with your shipment data. Parcelcraft makes extensive use of the Stripe API and the EasyPost API.
Stripe API
Parcelcraft adds metadata to your PaymentIntenets, Invoices, Shipping Rates and Products to manage shipment status and default options
Stripe Invoice and PaymentIntents metadata
When an invoice is created, our app automatically will determine if the invoice you've created is for a physical product or for a service. We use your Stripe Product shippable status, or if you've selected a shipping rate as part of your invoice to indicate via your Stripe metadata if an invoice is shippable. Our app will automatically add metadata to Stripe invoices prior to shipment. If an invoice uses a shipping rate or if any product in the invoice is shippable, metadata with a key of "ship_status" and a value of "unshipped" will be added to your invoice metadata. Invoices that are marked as unshipped will appear in your unshipped invoices list in Parcelcraft.
Prior to shipment
Supported metatdata prior to shipment
| Metadata key | Possible metadata values |
|---|---|
| ship_status | unshipped The invoice will appear in your unshipped invoices list canceled The invoice will appear in your canceled invoices list shipped We assume this was shipped or hand delivered outside of the Parcelcraft app back_ordered The invoice will appear in your backordred invoices list (no value) We assume this is a non-shippable invoice or the status has not been determined |
| is_return | true (as a string) when a shipment is created, the shipment will be created as a return shipment by default |
After shipment
PaymentIntents and Invoices will mirror each other's metadata values at the time of shipment. If no invoice exists for a paymentIntent, only the paymentIntent metadata will reflect these values:
| Metadata key | Metadata value example |
|---|---|
| ship_date | 2024-05-24T18:07:34Z |
| ship_status | shipped (Could be value of unshipped, canceled, back_ordered. The ship_status metadata will not exist if invoice or payment is considered to be non-shippable) |
| shipment_id | shp_bdf04565433... The EasyPost shipment ID |
| tracking_number | 9434600110368044455854 |
| tracking_URL | https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9434600110368044455854 (opens in a new tab) |
| service_name | USPS Ground Advantage |
| is_return | true (as a string) the shipment was a return label (this metadata key will be absent if the shipment was not a return shipment) |
Stripe Product metadata
All values are optional, but having product defaults help prepare your shipment according to your product metadata.
| Metadata key | Metadata value example |
|---|---|
| customs_description | SIM card |
| origin_country | US |
| tariff_code | 8523.52.00 |
| weight | 0.44 |
| weight_unit | Either gram, ounce, pound, or kilogram. Defaults to ounce |
| is_return | true Defaults to null or false |
Stripe Shipping Rate metadata
All values are optional, but having product defaults help prepare your shipment according to your shipping rate metadata, if you use shipping rates in your Stripe Invoices.
| Metadata key | Example | Description |
|---|---|---|
| carrier_id | ca_c38cd24... | Your EasyPost carrier id |
| package_code | Letter | The package code for your EasyPost carrier. Defaults to Package. See https://www.easypost.com/carriers (opens in a new tab) |
| packaging_weight | .26 | The weight of your packaging. The final weight of your package will be based on your product weight and product quantity |
| packaging_weight_unit | ounce | Either gram, ounce, pound, or kilogram. Defaults to ounce |
| service_code | Priority | The compatible service level (Ground, Priority NextDayAir) for your EasyPost carrier. See https://www.easypost.com/carriers (opens in a new tab) |
| width | 10 | The default packaging width in the dimension unit (inches or centimeters) as set in your Parcelcraft carrier settings |
| length | 5 | See above |
| height | 8 | See above |
Stripe Customer metadata
- Some addresses (for example shared office spaces) may require a company name for a successful shipment.
- If your Stripe customer record has a company metadata value, we'll automatically add their company name to the customer's shipping address when you create a shipment.
- Tip: Add a custom field called "company" in your Stripe payment links or checkout sessions, then use that data to modify your Stripe customer's metadata.
| Metadata key | Metadata value example |
|---|---|
| company | Acme Incorporated |