Create a payment session for a shipping label
create_checkout_linkTurns a decided shipment into a payment session for buying its shipping label: the checkout amount and a handoff URL that opens SMKlog checkout prefilled with the parcel. Use it after get_parcel_quote, passing the quote_id that call returned, so the price is reused and no second carrier call is spent. Without a quote_id it prices the shipment live from the fields. The result carries a session_id: keep it, and get_checkout_status tells you when the human has paid and when the label exists.
Side effects: it writes a session record (30-day life, readable through get_checkout_status) and is not idempotent. Calling it twice makes two sessions and, without a quote_id, spends two carrier calls. It never charges: no card is touched and nothing is reserved until the human confirms the contents certification and the carrier-adjustment consent on the page and pays there. A stale link simply reprices.
No session is returned when the shipment cannot be sold online: not a parcel (SMKlog does not arrange pallet or freight shipments), more than one box (one label per box), or an installed lithium battery crossing a border. Quote first to learn which case applies.
Parameter rules:
A valid quote_id overrides product, from_zip, to_zip, to_country and quantity. service is still honored.
An expired quote_id falls back to live pricing from the fields. If those were omitted too, the call fails with missing_required_fields, so pass them alongside an old id.
service is matched as a case-insensitive fragment of the display name ("Ground Advantage", "UPS Ground Saver"). A fragment that matches nothing silently anchors the quote's first rate, which is the top of the best-value ranking and not always the cheapest, so read the service field in the result.
from_zip is a real 5-digit US ZIP. to_zip follows to_country (US, CA, GB, DE or AU).
On the four international lanes the human completes the customs declaration on the page, and duty is billed to the recipient on arrival.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to_zip | No | Destination postal code: a 5-digit ZIP for the US, or the destination country's own postal code. Required unless quote_id is given. | |
| product | No | Plain-words item description. Required unless quote_id is given. | |
| service | No | Service to anchor the amount to, e.g. "USPS Ground Advantage". Omitted or unmatched, the amount anchors the quote's first rate, top of the best-value ranking rather than the cheapest; the human can still pick any service on the page. | |
| from_zip | No | Origin US ZIP code, 5 digits. Required unless quote_id is given. | |
| quantity | No | How many of the item ship together. Default 1. | |
| quote_id | No | The quote_id returned by a previous get_parcel_quote call. Valid for 15 minutes. | |
| to_country | No | Two-letter destination country: US (default), CA, GB, DE, AU. | US |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Standing caveats: live quote, human confirms consents and pays | |
| amount | Yes | Live-quoted checkout total for the anchored service, USD | |
| intent | Yes | Always "session" — this tool never charges | |
| method | No | Payment rails behind the checkout, e.g. stripe, card | |
| service | No | The service the amount is anchored to | |
| currency | Yes | ISO currency, USD | |
| session_id | No | Handle for get_checkout_status, shaped as_ plus a UUID, good for 30 days. Null only when the session record could not be stored. | |
| handoff_url | Yes | Opens the SMKlog checkout prefilled with this shipment | |
| quote_reused | No | True when the amount came from a quote_id you supplied, so no carrier call was spent. False when this tool priced the shipment live -- either because no quote_id was given, or because the one given had expired. | |
| identified_product_title | No | What the estimator understood the item to be |