postsale carriers

Carrier account management.

Subcommands

postsale carriers list
postsale carriers validate --input creds.json
postsale carriers delete <id> --yes

USPS label addresses: sender and return-to

A USPS carrier account carries two optional label addresses in its settings, separate from the account address and from the ship-from origin address:

Leave either blank and the ship-from address is used. Both are full addresses (name, street_line_1, city, state, postal_code, country_code; optional company, street_line_2, phone, email).

Set them with carriers update. Pass the account id and only the keys you are changing. The CLI reads the current account and merges your keys onto it before calling the API, so nothing you leave out is cleared and you never have to supply the credential fields that carriers list redacts. The account's status and carrier_type are never taken from you: to remove an account use carriers delete, which asks for confirmation.

# find the USPS account id (built_in: true is the house account)
postsale carriers list --human
postsale carriers update --yes --json '{
  "id": "<usps-account-id>",
  "settings": {
    "returnAddress": {
      "name": "Returns Dept", "street_line_1": "1 Warehouse Way",
      "city": "Austin", "state": "TX",
      "postal_code": "78701", "country_code": "US"
    }
  }
}'
# clear one: the label falls back to the ship-from address
postsale carriers update --yes \
  --json '{ "id": "<usps-account-id>", "settings": { "senderAddress": null } }'

Merge rules: omitted keys keep their current value; address, account_number, and data are only replaced by an explicit non-empty value, never cleared; settings merges key by key, and null on a settings key deletes it. The endpoint itself is a full replace of an array of accounts, which is why the CLI never sends a partial object through unmerged. The printed result is redacted the same way carriers list is (address, account_number, data stripped and named in _cli_meta.redacted_fields), so an update never echoes credentials to the terminal.

The merged settings is validated as a whole against the carrier's schema, so an unknown key or an incomplete address is rejected with a 422 that names the field.

When a USPS label is bought, the addresses in force at that moment are copied onto the shipment as sender_address and return_address. They are a historical record: postsale shipments get <id> shows what was printed even if the account settings change later.

The built-in USPS account

Accounts with the house-labels feature see an extra carrier in carriers list with built_in: true and a fixed nickname. It is Postsale's USPS account offered to customers who have no USPS account of their own:

• Postage is charged to the Postsale account's payment method, after the account owner accepts the built-in-labels terms once (the CLI surfaces this as an owner-action gate; it never accepts on your behalf).
• Rate shopping always includes it; a label purchase on it needs the feature on, the terms accepted, and a payment method on file. A test label needs none of those.
• You own only address, default, settings.senderAddress and settings.returnAddress on it. Everything else you send in an update is ignored, and it cannot be deleted.
• It ships from your Default Address origin address, so keep that one accurate.
• Pickup scheduling is refused on it, and it reports supports_schedule_pickup: false.

Status values

setup_incomplete (abandoned connection attempts are deleted after about two hours), setup_complete, needs_reauth (the carrier rejected the stored credentials; reconnect the account in the web app), deleted.

Schema

carriers.list, add, update, delete, validate

Agent tools

get_carriers, add_carrier, update_carrier, delete_carrier, validate_carrier