Carrier Packaging

Most carriers support their own package types, each with a specific package_id and package_code that you define in the packages object for a shipment. While the package_id and package_code properties are not required by ShipStation V2 API, most carriers will require at least the package_code to successfully return a label. Additionally, the carrier package you use can affect things like your rate (e.g., a USPS Flat Rate box will have a different rate than a generic package).

To see what types of packages your carrier supports and the associated properties, you can use the list carrier packages endpoint (see the API Reference for details).

Carrier packaging is distinct from using custom package types, which are custom packages where you define the package properties in advance, including dimensions, and only add the package_code to the packages object.

Example Request

This create label example uses the USPS Priority Mail service with a medium flat rate box package type. In the case of flat rate boxes, you will declare package weight (to ensure the shipment does not exceed the flat rate maximum) but would not declare package dimensions.

curl -i -X POST \
  https://api.shipstation.com/v2/labels \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ship_to_service_point_id": "614940",
    "ship_from_service_point_id": "614940",
    "shipment": {
      "carrier_id": "se-1234567",
      "service_code": "usps_first_class_mail",
      "requested_shipment_service": "usps_priority_mail",
      "external_order_id": "1232434",
      "hold_until_date": "2025-01-15T00:00:00.000Z",
      "ship_by_date": "2025-01-15T00:00:00.000Z",
      "deliver_by_date": "2025-01-20T00:00:00.000Z",
      "retail_rate": {
        "currency": "usd",
        "amount": 12
      },
      "store_id": "se-12345",
      "items": [],
      "notes_from_buyer": "Please handle with care",
      "notes_to_buyer": "Thank you for your order!",
      "notes_for_gift": "Happy Birthday!",
      "internal_notes": "Check packaging before shipping",
      "is_gift": true,
      "assigned_user": "user@example.com",
      "amount_paid": {
        "currency": "usd",
        "amount": 12
      },
      "shipping_paid": {
        "currency": "usd",
        "amount": 12
      },
      "tax_paid": {
        "currency": "usd",
        "amount": 12
      },
      "zone": 1,
      "display_scheme": "label",
      "tax_identifiers": [
        {
          "taxable_entity_type": "shipper",
          "identifier_type": "vat",
          "issuing_authority": "US",
          "value": "value"
        }
      ],
      "external_shipment_id": "1234556",
      "shipment_number": "10001",
      "ship_date": "2018-09-23T00:00:00Z",
      "ship_to": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instruction",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "ship_from": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instructions",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "warehouse_id": null,
      "return_to": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instructions",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "is_return": true,
      "confirmation": "none",
      "customs": {
        "terms_of_trade_code": "ddp",
        "contents": "gift",
        "non_delivery": "return_to_sender"
      },
      "advanced_options": {
        "bill_to_account": "123456789",
        "bill_to_country_code": "US",
        "bill_to_party": "third_party",
        "bill_to_postal_code": "28005",
        "contains_alcohol": true,
        "delivered_duty_paid": true,
        "dry_ice": true,
        "dry_ice_weight": {
          "value": 23,
          "unit": "pound"
        },
        "non_machinable": true,
        "saturday_delivery": true,
        "fedex_freight": {
          "shipper_load_and_count": "shipper_load_and_count",
          "booking_confirmation": "today"
        },
        "use_ups_ground_freight_pricing": true,
        "freight_class": "77.5",
        "custom_field1": "custom field 1",
        "custom_field2": "custom field 2",
        "custom_field3": "custom field 3",
        "origin_type": null,
        "additional_handling": true,
        "shipper_release": true,
        "collect_on_delivery": {
          "payment_type": "any",
          "payment_amount": {
            "currency": "USD",
            "amount": 12
          }
        },
        "third_party_consignee": true,
        "dangerous_goods": true,
        "dangerous_goods_contact": {
          "name": "Michael Robinson",
          "phone": "123456578789"
        },
        "movement_indicator": "b2b",
        "windsor_framework_details": {
          "movement_indicator": "b2b",
          "not_at_risk": true
        },
        "ancillary_endorsements_option": "forward",
        "return_pickup_attempts": 3,
        "own_document_upload": false,
        "limited_quantity": false,
        "event_notification": false,
        "fragile": false,
        "delivery_as_addressed": false,
        "return_after_first_attempt": false,
        "regulated_content_type": null,
        "netstamps_options": {
          "row": 1,
          "column": 1
        },
        "suppress_carrier_generated_documents": [
          "commercial_invoice"
        ],
        "transparency_codes": [
          {
            "order_item_id": "12345678901234",
            "codes": [
              "AZ:XXXXXXXXXXXX"
            ]
          }
        ]
      },
      "insurance_provider": "none",
      "tags": [],
      "order_source_code": "amazon_ca",
      "packages": [
        {
          "package_id": "se-123456",
          "package_code": "thick_envelope",
          "package_name": "Flat Rate Envelope",
          "weight": {
            "value": 23,
            "unit": "pound"
          },
          "dimensions": {
            "unit": "inch",
            "length": 2,
            "width": 2,
            "height": 1
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0
          },
          "label_messages": {
            "reference1": "Reference",
            "reference2": "Reference 2",
            "reference3": "Reference 3"
          },
          "external_package_id": "se-1234545",
          "content_description": "Hand knitted wool socks",
          "products": []
        }
      ],
      "comparison_rate_type": "retail"
    },
    "is_return_label": true,
    "rma_number": "asd12323",
    "charge_event": "carrier_default",
    "outbound_label_id": "se-28529731",
    "test_label": true,
    "validate_address": "no_validation",
    "voided_at": "2018-09-23T15:00:00.000Z",
    "refund_details": {
      "amount_paid": {
        "currency": "usd",
        "amount": 12
      },
      "amount_requested": {
        "currency": "usd",
        "amount": 12
      },
      "amount_approved": {
        "currency": "usd",
        "amount": 12
      },
      "amount_credited": {
        "currency": "usd",
        "amount": 12
      }
    },
    "label_download_type": "url",
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
    "form_download": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "qr_code_download": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "paperless_download": {
      "href": "https://example.com/resource",
      "instructions": "any instructions",
      "handoff_code": "122334"
    },
    "insurance_claim": {
      "href": "https://example.com/resource",
      "type": "child"
    }
  }'

In the create label response, the package_code property will be a property in both the shipment object and the packages object. In the create shipment response, the package_code property will be in the packages object only.

Carrier Packaging

Example Request

Related Guides

Was this helpful?