# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Sendcloud Shipments API version: 1.0.0 extends: openapi/sendcloud-shipments-api-openapi.yml actions: - target: $.info update: x-apievangelist-phrasing: method: generated generated: '2026-10-01' generator: build-phrasing.py label: Generated by API Evangelist operations: 12 - target: $.paths['/shipments/announce'].post update: x-apievangelist-phrasing: intent: Create and announce a shipment synchronously effect: write questions: - How do I create a shipment and get the label in the same response? - Can I announce a shipment and wait for the carrier to confirm? instructions: - text: Announce shipment of parcels {parcels} and wait for the label. slots: parcels: requestBody.parcels - text: Create a shipment now and return the carrier response. method: generated generated: '2026-10-01' - target: $.paths['/shipments'].get update: x-apievangelist-phrasing: intent: List shipments effect: read questions: - Which shipments have I created or imported recently? - Can I filter shipments by tracking number or order number? - What shipments were announced before a certain date? instructions: - text: List shipments with status {parcel_status}. slots: parcel_status: query.parcel_status - text: Find the shipment with tracking number {tracking_number}. slots: tracking_number: query.tracking_number - text: List shipments announced after {announced_after}. slots: announced_after: query.announced_after method: generated generated: '2026-10-01' - target: $.paths['/shipments'].post update: x-apievangelist-phrasing: intent: Create and announce a shipment asynchronously effect: write questions: - Can I submit a shipment and have it announced in the background? - What's the non-blocking way to announce a shipment? instructions: - text: Submit parcels {parcels} as a shipment announced in the background. slots: parcels: requestBody.parcels - text: Queue a new shipment for asynchronous announcement. method: generated generated: '2026-10-01' - target: $.paths['/shipments/announce-with-shipping-rules'].post update: x-apievangelist-phrasing: intent: Announce a shipment with shipping rules, synchronously effect: write questions: - Can my shipping rules pick the method when I announce a shipment and wait for it? - How do I apply my shipping defaults and get the label back immediately? instructions: - text: Announce parcels {parcels} now applying shipping rules {apply_shipping_rules}. slots: parcels: requestBody.parcels apply_shipping_rules: requestBody.apply_shipping_rules - text: Create a shipment with my shipping defaults {apply_shipping_defaults} and wait for the label. slots: apply_shipping_defaults: requestBody.apply_shipping_defaults method: generated generated: '2026-10-01' - target: $.paths['/shipments/create-with-shipping-rules'].post update: x-apievangelist-phrasing: intent: Announce a shipment with shipping rules, asynchronously effect: write questions: - Can shipping rules and defaults be applied to a shipment announced in the background? - Is there an async version of creating shipments with my shipping rules? instructions: - text: Queue parcels {parcels} for background announcement with shipping rules {apply_shipping_rules}. slots: parcels: requestBody.parcels apply_shipping_rules: requestBody.apply_shipping_rules - text: Create an async shipment using shipping defaults {apply_shipping_defaults}. slots: apply_shipping_defaults: requestBody.apply_shipping_defaults method: generated generated: '2026-10-01' - target: $.paths['/addresses/validate'].post update: x-apievangelist-phrasing: intent: Validate a shipping address effect: read questions: - Can I check that a shipping address is valid before I create a label? - Which carrier do I need to name when checking an address for deliverability? instructions: - text: Validate the address {address} for carrier {carrier_code}. slots: address: requestBody.address carrier_code: requestBody.carrier_code - text: Check whether {address} is a deliverable address before shipping with {carrier_code}. slots: address: requestBody.address carrier_code: requestBody.carrier_code method: generated generated: '2026-10-01' - target: $.paths['/shipments/{id}'].get update: x-apievangelist-phrasing: intent: Get a shipment effect: read questions: - How do I look up one shipment by its ID? - What parcels and status does a particular shipment have? instructions: - text: Show shipment {id}. slots: id: path.id - text: Get the details of shipment {id}. slots: id: path.id method: generated generated: '2026-10-01' - target: $.paths['/shipments/{id}/cancel'].post update: x-apievangelist-phrasing: intent: Cancel an announced shipment effect: destructive questions: - Can I cancel a shipment that's already been announced to the carrier? - Does every carrier allow announced shipments to be cancelled? instructions: - text: Cancel shipment {id}. slots: id: path.id - text: Cancel announced shipment {id} with the carrier. slots: id: path.id method: generated generated: '2026-10-01' - target: $.paths['/shipments/{id}/return-portal-url'].get update: x-apievangelist-phrasing: intent: Get the return portal link for a shipment effect: read questions: - How do I get a return portal link to send with a shipment? - Which return portal URL belongs to a given shipment? instructions: - text: Get the return portal URL for shipment {id}. slots: id: path.id - text: Show the return portal link of shipment {id}. slots: id: path.id method: generated generated: '2026-10-01' - target: $.paths['/integrations/{id}/shipments'].get update: x-apievangelist-phrasing: intent: List orders imported from a shop integration effect: read questions: - Which orders were imported from one of my webshop integrations? - Can I filter a shop's imported orders by date range or order number? instructions: - text: List imported orders for integration {id}. slots: id: path.id - text: Show orders imported into integration {id} between {start_date} and {end_date}. slots: id: path.id start_date: query.start_date end_date: query.end_date method: generated generated: '2026-10-01' - target: $.paths['/integrations/{id}/shipments'].post update: x-apievangelist-phrasing: intent: Push orders into a shop integration effect: write questions: - How do I insert orders from my shop system into an API integration? - Can I update orders I already pushed to an integration? instructions: - text: Insert a list of orders into integration {id}. slots: id: path.id - text: Create or update shop orders in integration {id}. slots: id: path.id method: generated generated: '2026-10-01' - target: $.paths['/integrations/{id}/shipments/delete'].post update: x-apievangelist-phrasing: intent: Delete an order from a shop integration effect: destructive questions: - How do I remove an order from Sendcloud after it was cancelled in my shop? - Can I delete an imported shop order from an integration? instructions: - text: Delete a shop order from integration {id}. slots: id: path.id - text: Remove the cancelled order from integration {id}. slots: id: path.id method: generated generated: '2026-10-01'