---
title: "Create a shipping label"
method: POST
path: "/transactions"
tags: ["Transactions"]
---

# Create a shipping label

`POST /transactions`

Creates a new transaction object and purchases the shipping label using a rate object that has previously been created.

Alternatively, creates a new transaction object and purchases the shipping label instantly using shipment details, an existing carrier account, and an existing service level token.

## Headers

- `SHIPPO-API-VERSION` string

## Request body

- union
  - TransactionCreateRequest
    - `async` boolean
    - `label_file_type` 'PNG' | 'PNG_2.3x7.5' | 'PDF' | 'PDF_2.3x7.5' | 'PDF_4x6' | 'PDF_4x8' | 'PDF_A4' | 'PDF_A5' | 'PDF_A6' | 'ZPLII' — Print format of the [label](https://docs.goshippo.com/docs/shipments/shippinglabelsizes/). If empty, will use the default format set from [the Shippo dashboard.](https://apps.goshippo.com/settings/labels)
    - `metadata` string
    - `rate` string, required
    - `order` string
  - InstantTransactionCreateRequest
    - `async` boolean
    - `carrier_account` string, required
    - `label_file_type` 'PNG' | 'PNG_2.3x7.5' | 'PDF' | 'PDF_2.3x7.5' | 'PDF_4x6' | 'PDF_4x8' | 'PDF_A4' | 'PDF_A6' | 'ZPLII'
    - `metadata` string
    - `servicelevel_token` string, required
    - `shipment` ShipmentCreateRequest, required
      - `extra` ShipmentExtra — An object holding optional extra services to be requested.
        - `accounts_receivable_customer_account` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `alcohol` Alcohol — Indicates that a shipment contains Alcohol (Fedex and UPS only).
          - `contains_alcohol` boolean — Mandatory for Fedex and UPS. Specifies that the package contains Alcohol.
          - `recipient_type` 'licensee' | 'consumer' — Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
        - `ancillary_endorsement` 'FORWARDING_SERVICE_REQUESTED' | 'RETURN_SERVICE_REQUESTED' — Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
        - `appropriation_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `authority_to_leave` boolean — Request `true` to give carrier permission to leave the parcel in a safe place if no one answers the door (where supported). When set to `false`, if no one is available to receive the item, the parcel will not be left (*surcharges may be applicable).
        - `bill_of_lading_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `billing` Billing — Specify billing details (UPS, FedEx, and DHL Germany only).
          - `account` string — Account number to be billed. (For DHL Germany, leave this field blank.)
          - `country` string, iso-3166 — Country iso2 code of account number to be billed (required for UPS third party billing only).
          - `participation_code` string — 2 digit code used to override your default participation code associated with your DHL Germany account.
          - `type` 'SENDER' | 'RECIPIENT' | 'THIRD_PARTY' | 'THIRD_PARTY_CONSIGNEE' | 'COLLECT' — Party to be billed. (Leave blank for DHL Germany.)
          - `zip` string — ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).
        - `bypass_address_validation` boolean — Bypasses address validation (USPS, UPS, & LaserShip only).
        - `carbon_neutral` boolean — Request carbon offsets by passing true (UPS only).
        - `carrier_hub_id` string — Identifies the carrier injection site.
        - `carrier_hub_travel_time` integer — Travel time in hours from fulfillment center to carrier injection site.
        - `COD` COD — Specify collection on delivery details (UPS only).
          - `amount` string — Amount to be collected.
          - `currency` string — Currency for the amount to be collected. Currently only USD is supported for UPS.
          - `payment_method` 'SECURED_FUNDS' | 'CASH' | 'ANY' — Secured funds include money orders, certified cheques and others (see [UPS](https://www.ups.com/content/us/en/shipping/time/service/value_added/cod.html) for details). If no payment_method inputted the value defaults to "ANY".)
        - `cod_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `container_type` string — Specify container type.
        - `critical_pull_time` string — Carrier arrival time to pickup packages from the fulfillment center. UTC format: `%Y-%m-%dT%H:%M:%SZ`
        - `customer_branch` string — Specify customer branch (Lasership only).
        - `customer_reference` CustomerReference — Specify the reference field on the label (FedEx and UPS only).
          - `prefix` string — Custom prefix for customer reference field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
          - `value` string — Optional text to be printed on the shipping label for customer reference. Up to 40 characters. If this is provided, reference_1 will be ignored. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 40 characters (Express services); Max 30 characters (Ground services) |
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `dangerous_goods` DangerousGoodsObject — Container for specifying the presence of dangerous materials. This is specific to USPS, and if any contents are provided, only certain USPS service levels will be eligible. For more information, see our [guide on hazardous or dangerous materials shipping](https://docs.goshippo.com/docs/shipments/hazmat/).
          - `contains` boolean — Indicates if the shipment contains dangerous goods.
          - `biological_material` DangerousGoodsBiologicalMaterial — Container for specifying the presence of biological material.
            - `contains` boolean — Indicates if the shipment contains biological material.
          - `lithium_batteries` DangerousGoodsLithiumBatteries — Container for specifying the presence of lithium batteries.
            - `contains` boolean — Indicates if the shipment contains lithium batteries.
        - `dangerous_goods_code` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' — Dangerous Goods Code (DHL eCommerce only). See [Category Codes](https://api-legacy.dhlecs.com/docs/v2/appendix.html#dangerous-goods)
        - `dealer_order_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `delivery_instructions` string — Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).
        - `dept_number` DepartmentNumber — Specify the department number field on the label (FedEx and UPS only).
          - `prefix` string — Custom prefix for department number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
          - `value` string — Optional text to be printed on the shipping label for department number. Up to 40 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `dry_ice` DryIce — Specify that the package contains Dry Ice (FedEx, Veho, and UPS only).
          - `contains_dry_ice` boolean — Mandatory. Specifies that the package contains Dry Ice.
          - `weight` string — Mandatory. Units must be in Kilograms. Cannot be greater than package weight.
        - `fda_product_code` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `fulfillment_center` string — The fulfilment center where the package originates from.
        - `insurance` Insurance — To add 3rd party insurance powered by [XCover](https://docs.goshippo.com/docs/shipments/shippinginsurance/), specify `amount`, `content`, and `currency`. Alternatively, you can choose carrier provided insurance by additionally specifying `provider` (UPS, FedEx and OnTrac only). If you do not want to add insurance to your shipment, do not set these parameters.
          - `amount` string — Declared value of the goods you want to insure.
          - `content` string — Description of package content.
          - `currency` string, iso-4217 — Currency for the amount value. Currently only USD is supported for FedEx and UPS.
          - `provider` 'FEDEX' | 'UPS' | 'ONTRAC' — To have insurance cover provided by a carrier directly instead of Shippo's provider (XCover), set `provider` to `FEDEX`, `UPS`, or `ONTRAC`.
        - `invoice_number` InvoiceNumber — Specify the invoice number field on the label (FedEx and UPS only).
          - `prefix` string — Custom prefix for invoice number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
          - `value` string — Optional text to be printed on the shipping label for invoice number. Up to 40 characters. If provided, this will be used on the label instead of shipment.customs_declaration.invoice. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `is_return` boolean — This field specifies if it is a scan-based return shipment. See the [Create a return shipment](https://docs.goshippo.com/docs/shipments/returns/) section for more details.
        - `lasership_attrs` ShipmentExtraLasershipAttributesEnum[] — Specify Lasership Attributes (Lasership only). Multiple options accepted.
        - `lasership_declared_value` string — Declared value (Lasership only). Defaults to `50.00`.
        - `manifest_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `model_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `part_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `po_number` PoNumber — Specify the PO number field on the label (FedEx and UPS only).
          - `prefix` string — Custom prefix for PO number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
          - `value` string — Optional text to be printed on the shipping label for PO number. Up to 40 characters. If this is provided, reference_2 will be ignored. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `preferred_delivery_timeframe` '10001200' | '12001400' | '14001600' | '16001800' | '18002000' | '19002100' — Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is `HHMMHHMM`
        - `premium` boolean — Add premium service to a shipment (DHL Germany international shipments only).
        - `production_code` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `purchase_request_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `qr_code_requested` boolean — Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).
        - `reference_1` string — Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 40 characters (Express services); Max 30 characters (Ground services) |
        - `reference_2` string — Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters. For DHL eCommerce, this field can be used for billing reference. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
        - `request_retail_rates` boolean — Returns retail rates instead of account-based rates (UPS and FedEx only).
        - `return_service_type` union — Request additional return option for return shipments (UPS and Lasership only).
          - 'PRINT_AND_MAIL' | 'ATTEMPT_1' | 'ATTEMPT_3' | 'ELECTRONIC_LABEL'
          - 'NO_RETURN'
        - `rma_number` RmaNumber — Specify the RMA number field on the label (FedEx and UPS only).
          - `prefix` string — Custom prefix for RMA number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
          - `value` string — Optional text to be printed on the shipping label for RMA number. Up to 40 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 20 characters |
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `saturday_delivery` boolean — Marks shipment as to be delivered on a Saturday.
        - `salesperson_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `serial_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `signature_confirmation` 'STANDARD' | 'ADULT' | 'CERTIFIED' | 'INDIRECT' | 'CARRIER_CONFIRMATION' — Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only).
        - `store_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `transaction_reference_number` UPSReferenceFields
          - `prefix` string — Custom prefix text.
          - `value` string — Label reference text. 35 character limit.
          - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
        - `usmca_eligible` boolean — UPS only. Request USMCA (United States-Mexico-Canada Agreement) preferential tariff treatment. When enabled, it includes the USMCA eligibility declaration in customs documentation. Supported routes and value limits: - USA/Canada → Mexico: ≤ $1,000 USD - Canada/Mexico → USA: ≤ $2,500 USD - USA/Mexico → Canada: ≤ $3,300 CAD Only for declaration-only shipments, full USMCA - FormType 04 (Certificate of Origin) is not supported.
      - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
      - `shipment_date` string — Date the shipment will be tendered to the carrier. Must be in the format `2014-01-18T00:35:03.463Z`. Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
      - `address_from` union, required
        - AddressCreateRequest — Address represents the address as retrieved from the database
          - `name` string — **required for purchase** First and Last Name of the addressee **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
          - `company` string — Company Name **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 35 characters; Either company or name required |
          - `street1` string — **required for purchase** First street line. Usually street number and street name (except for DHL Germany, see street_no). **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street2` string — Second street line. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street3` string — Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street_no` string — Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
          - `city` string — **required for purchase** Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Max 35 characters |
          - `state` string — **required for purchase for some countries** State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
          - `zip` string — **required for purchase** Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 10 characters |
          - `country` string, required — ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like `US` or `DE`. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this [guide](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a list of country codes. Sending a country is always required.
          - `phone` string — Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Min 1, max 15 characters | | USPS | Sender phone required for shipments during label purchase; Min 8, max 15 digits |
          - `email` string — E-mail address of the contact person, RFC3696/5321-compliant. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 80 characters | | USPS | Sender email required for shipments during label purchase |
          - `is_residential` boolean
          - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
          - `validate` boolean — Set to true to validate Address object.
        - string — [Address](/shippoapi/public-api/addresses) `object_id` of a previously created address.
      - `address_return` union
        - AddressCreateRequest — Address represents the address as retrieved from the database
          - `name` string — **required for purchase** First and Last Name of the addressee **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
          - `company` string — Company Name **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 35 characters; Either company or name required |
          - `street1` string — **required for purchase** First street line. Usually street number and street name (except for DHL Germany, see street_no). **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street2` string — Second street line. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street3` string — Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street_no` string — Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
          - `city` string — **required for purchase** Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Max 35 characters |
          - `state` string — **required for purchase for some countries** State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
          - `zip` string — **required for purchase** Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 10 characters |
          - `country` string, required — ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like `US` or `DE`. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this [guide](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a list of country codes. Sending a country is always required.
          - `phone` string — Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Min 1, max 15 characters | | USPS | Sender phone required for shipments during label purchase; Min 8, max 15 digits |
          - `email` string — E-mail address of the contact person, RFC3696/5321-compliant. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 80 characters | | USPS | Sender email required for shipments during label purchase |
          - `is_residential` boolean
          - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
          - `validate` boolean — Set to true to validate Address object.
        - string — [Address](/shippoapi/public-api/addresses) `object_id` of a previously created address.
      - `address_to` union, required
        - AddressCreateRequest — Address represents the address as retrieved from the database
          - `name` string — **required for purchase** First and Last Name of the addressee **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
          - `company` string — Company Name **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 35 characters; Either company or name required |
          - `street1` string — **required for purchase** First street line. Usually street number and street name (except for DHL Germany, see street_no). **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street2` string — Second street line. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street3` string — Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
          - `street_no` string — Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
          - `city` string — **required for purchase** Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Max 35 characters |
          - `state` string — **required for purchase for some countries** State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
          - `zip` string — **required for purchase** Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 10 characters |
          - `country` string, required — ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like `US` or `DE`. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this [guide](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a list of country codes. Sending a country is always required.
          - `phone` string — Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Min 1, max 15 characters | | USPS | Sender phone required for shipments during label purchase; Min 8, max 15 digits |
          - `email` string — E-mail address of the contact person, RFC3696/5321-compliant. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 80 characters | | USPS | Sender email required for shipments during label purchase |
          - `is_residential` boolean
          - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
          - `validate` boolean — Set to true to validate Address object.
        - string — [Address](/shippoapi/public-api/addresses) `object_id` of a previously created address.
      - `customs_declaration` union
        - CustomsDeclarationCreateRequest
          - `aes_itn` string — **required if eel_pfc is `AES_ITN`** AES / ITN reference of the shipment.
          - `b13a_filing_option` 'FILED_ELECTRONICALLY' | 'SUMMARY_REPORTING' | 'NOT_REQUIRED' — B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). [More information on reporting commercial exports from Canada.](https://www.cbsa-asfc.gc.ca/services/export/guide-eng.html) Allowed values available [here](/shippoapi/public-api/customs-declaration-b13a-filing-option)
          - `b13a_number` string — **must be provided if and only if b13a_filing_option is provided** Represents the Proof of Report (POR) Number when b13a_filing_option is `FILED_ELECTRONICALLY`; the Summary ID Number when b13a_filing_option is `SUMMARY_REPORTING`; or the Exemption Number when b13a_filing_option is `NOT_REQUIRED`.
          - `certificate` string — Certificate reference of the shipment.
          - `certify` boolean, required — Expresses that the certify_signer has provided all information of this customs declaration truthfully.
          - `certify_signer` string, required — Name of the person who created the customs declaration and is responsible for the validity of all information provided.
          - `commercial_invoice` boolean
          - `contents_explanation` string — **required if contents_type is `OTHER`** Explanation of the type of goods of the shipment.
          - `disclaimer` string — Disclaimer for the shipment and customs information that have been provided. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 554 characters |
          - `duties_payor` object — Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.
            - `account` string — Account number to be billed for duties.
            - `type` 'SENDER' | 'RECIPIENT' | 'THIRD_PARTY' — Party to be billed for duties.
            - `address` object
              - …
          - `exporter_identification` CustomsExporterIdentification — Additional exporter identification that may be required to ship in certain countries
            - `eori_number` string — Economic Operators' Registration and Identification (EORI) number. Must start with a 2 character country code followed by a 6-17 character alphanumeric identifier (e.g. PL1234567890ABCDE). [More information on EORI.](https://ec.europa.eu/taxation_customs/business/customs-procedures/general-overview/economic-operators-registration-identification-number-eori_en)
            - `tax_id` CustomsTaxIdentification — Tax identification that may be required to ship in certain countries. Typically used to assess duties on goods that are crossing a border.
              - …
          - `exporter_reference` string — Exporter reference of an export shipment.
          - `importer_reference` string — Importer reference of an import shipment.
          - `is_vat_collected` boolean — Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.
          - `invoice` string — Invoice reference of the shipment.
          - `license` string — License reference of the shipment.
          - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
          - `notes` string — Additional notes to be included in the customs declaration.
          - `address_importer` AddressImporter — Object that represents the address of the importer
            - `name` string — First and Last Name of the addressee
            - `company` string — Company Name
            - `street1` string — First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).
            - `street2` string — Second street line, 35 character limit.
            - `street3` string — Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments.
            - `street_no` string — Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
            - `city` string — Name of a city
            - `state` string — **required for purchase for some countries** State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations.
            - `zip` string — Postal code of an Address.
            - `country` string — Example: `US` or `DE`. All accepted values can be found on the [Official ISO Website](http://www.iso.org/). Sending a country is always required.
            - `phone` string — Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.
            - `email` string — E-mail address of the contact person, RFC3696/5321-compliant.
            - `is_residential` boolean — Indicates whether the address provided is a residential address or not.
          - `contents_type` 'DOCUMENTS' | 'GIFT' | 'SAMPLE' | 'MERCHANDISE' | 'HUMANITARIAN_DONATION' | 'RETURN_MERCHANDISE' | 'OTHER', required — Type of goods of the shipment. Allowed values available [here](/shippoapi/public-api/customs-declaration-contents-type)
          - `eel_pfc` 'NOEEI_30_37_a' | 'NOEEI_30_37_h' | 'NOEEI_30_37_f' | 'NOEEI_30_36' | 'AES_ITN' — EEL / PFC type of the shipment. For most shipments from the US to CA, `NOEEI_30_36` is applicable; for most other shipments from the US, `NOEEI_30_37_a` is applicable. Allowed values available [here](/shippoapi/public-api/customs-declaration-eelpfc)
          - `incoterm` 'DDP' | 'DDU' | 'FCA' | 'DAP' | 'eDAP' — The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express, FedEx, and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available [here](/shippoapi/public-api/customs-declaration-incoterm) Carrier-specific restrictions are in the table below. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Must be one of DDP, DDU, FCA, DAP |
          - `items` CustomsItemCreateRequest[], required
            - `description` string, required — Text description of your item.
            - `eccn_ear99` string — Export Control Classification Number, required on some exports from the United States.
            - `mass_unit` 'g' | 'kg' | 'lb' | 'oz', required — The unit used for weight.
            - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
            - `net_weight` string, required — Total weight of this item, i.e. quantity * weight per item.
            - `origin_country` string, required — Country of origin of the item. Example: `US` or `DE`. All accepted values can be found on the [Official ISO Website](http://www.iso.org/).
            - `quantity` integer, required — Quantity of this item in the shipment you send. Must be greater than 0.
            - `sku_code` string — SKU code of the item, which is required by some carriers.
            - `hs_code` string — HS code of the item, which is required by some carriers. If `tariff_number` is not provided, `hs_code` will be used. If both `hs_code` and `tariff_number` are provided, `tariff_number` will be used. 50 character limit.
            - `tariff_number` string — The tariff number of the item. If `tariff_number` is not provided, `hs_code` will be used. If both `hs_code` and `tariff_number` are provided, `tariff_number` will be used. 12 character limit.
            - `value_amount` string, required — Total value of this item, i.e. quantity * value per item.
            - `value_currency` string, required — Currency used for value_amount. The [official ISO 4217](http://www.xe.com/iso4217.php) currency codes are used, e.g. `USD` or `EUR`.
          - `non_delivery_option` 'ABANDON' | 'RETURN', required — Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available [here](/shippoapi/public-api/customs-declaration-non-delivery-option)
          - `test` boolean
        - string — [Customs Declaration](/shippoapi/public-api/customs-declarations) `object_id` of a previously created customs declaration.
      - `async` boolean
      - `carrier_accounts` string[] — List of [Carrier Accounts](/shippoapi/public-api/carrier-accounts) `object_id`s used to filter the returned rates. If set, only rates from these carriers will be returned.
      - `parcels` union[], required — List of parcels to be shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 items |
        - union
          - ParcelCreateRequest
            - `extra` ParcelExtra — An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the `extra` field of the parcel object.
              - …
            - `metadata` string
            - `mass_unit` 'g' | 'kg' | 'lb' | 'oz', required — The unit used for weight.
            - `weight` string, required — Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
            - `distance_unit` 'cm' | 'in' | 'ft' | 'm' | 'mm' | 'yd', required — The measure unit used for length, width and height.
            - `height` string, required — Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
            - `length` string, required — Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
            - `width` string, required — Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
          - ParcelCreateFromTemplateRequest
            - `extra` ParcelExtra — An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the `extra` field of the parcel object.
              - …
            - `metadata` string
            - `mass_unit` 'g' | 'kg' | 'lb' | 'oz', required — The unit used for weight.
            - `weight` string, required — Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
            - `template` union, required — If template is passed, `length`, `width`, `height`, and `distance_unit` are not required
              - …
          - string — [Parcel](/shippoapi/public-api/parcels) `object_id` of a previously created parcel.
    - `order` string

## Response `201`

Created transaction

- Transaction
  - `commercial_invoice_url` string — A URL pointing to the commercial invoice as a 8.5x11 inch PDF file. A value will only be returned if the Transactions has been processed successfully and if the shipment is international.
  - `created_by` object, nullable — An object with details about the user who created the Transaction (purchased the label). A value will be returned only for Transactions that can be associated with a specific user, e.g. when a logged-in user purchases a label via the Shippo Web application; but not for Transactions purchased e.g. via the API using a ShippoToken, which is associated with the account but not any specific user.
    - `first_name` string
    - `last_name` string
    - `username` string
  - `eta` string — The estimated time of arrival according to the carrier.
  - `label_file_type` 'PNG' | 'PNG_2.3x7.5' | 'PDF' | 'PDF_2.3x7.5' | 'PDF_4x6' | 'PDF_4x8' | 'PDF_A4' | 'PDF_A5' | 'PDF_A6' | 'ZPLII' — Print format of the [label](https://docs.goshippo.com/docs/shipments/shippinglabelsizes/). If empty, will use the default format set from [the Shippo dashboard.](https://apps.goshippo.com/settings/labels)
  - `label_url` string — A URL pointing directly to the label in the format you've set in your settings. A value will only be returned if the Transactions has been processed successfully.
  - `messages` ResponseMessage[]
    - `source` string — Origin of message
    - `code` string — Classification of message
    - `text` string — Message content
  - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  - `object_created` string, date-time — Date and time of Transaction creation.
  - `object_id` string — Unique identifier of the given Transaction object.
  - `object_owner` string — Username of the user who created the Transaction object.
  - `object_state` 'VALID' | 'INVALID' — Indicates the validity of the enclosing object
  - `object_updated` string, date-time — Date and time of last Transaction update.
  - `parcel` string — Object ID of the Parcel object that is being shipped.
  - `qr_code_url` string — A URL pointing directly to the QR code in PNG format. A value will only be returned if requested using qr_code_requested flag and the carrier provides such an option.
  - `rate` union — ID of the Rate object for which a Label has to be obtained. If you purchase a label by calling the transaction endpoint without a rate (instalabel), this field will be a simplified Rate object in the Transaction model returned from the POST request. Note, only rates less than 7 days old can be purchased to ensure up-to-date pricing.
    - CoreRate
      - `amount` string — Final Rate price, expressed in the currency used in the sender's country.
      - `amount_local` string — Final Rate price, expressed in the currency used in the recipient's country.
      - `currency` string — Currency used in the sender's country, refers to `amount`. The [official ISO 4217](http://www.xe.com/iso4217.php) currency codes are used, e.g. `USD` or `EUR`.
      - `currency_local` string — Currency used in the recipient's country, refers to `amount_local`. The [official ISO 4217](http://www.xe.com/iso4217.php) currency codes are used, e.g. `USD` or "EUR".
      - `object_id` string — Unique identifier of the Rate object.
      - `provider` string — Carrier offering the rate, e.g., `FedEx` or `Deutsche Post DHL`.
      - `carrier_account` string — Object ID of the carrier account that has been used to retrieve the rate.
      - `servicelevel_name` string — Service level name, e.g. `Priority Mail` or `FedEx Ground®`. A service level commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. These names vary depending on the provider. See [Service Levels](/shippoapi/public-api/service-levels).
      - `servicelevel_token` string — Token of the Rate's servicelevel, e.g. `usps_priority` or `fedex_ground`. See [servicelevels](/shippoapi/public-api/service-levels).
    - string
  - `status` 'WAITING' | 'QUEUED' | 'SUCCESS' | 'ERROR' | 'REFUNDED' | 'REFUNDPENDING' | 'REFUNDREJECTED' — Indicates the status of the Transaction.
  - `test` boolean — Indicates whether the object has been created in test mode.
  - `tracking_number` string — The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully.
  - `tracking_status` 'UNKNOWN' | 'PRE_TRANSIT' | 'TRANSIT' | 'DELIVERED' | 'RETURNED' | 'FAILURE' — Indicates the high level status of the shipment.
  - `tracking_url_provider` string — A link to track this item on the carrier-provided tracking website. A value will only be returned if tracking is available and the carrier provides such a service.

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/goshippo/apis/shippo-address-api.md) · [All operations](https://skmtc.net/goshippo/apis/shippo-address-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goshippo/shippo-address-api/revisions/26fcc6af452a/schema)