@shipengine/connect-carrier-api

{ "openapi": "3.0.1", "info": { "title": "Shipping API", "description": "This API specification describes the canonical ShipEngine Shipping API connector module.", "version": "1.28.2" }, "paths": { "/Register": { "post": { "tags": [ "Account Setup" ], "description": "This method is used to authenticate with your application. It is responsible for verifying the supplied\r\nuser credentials and establishing or renewing a connection. The authentication information will be\r\nstored in the metadata object and will be included in all request bodies. All applications must\r\nimplement the Register method.", "operationId": "Register", "requestBody": { "description": "An object containing the authentication information gathered using the\r\n connection form you created for your application. It will contain whatever fields you defined in this form.\r\n Your method must then use this data to perform authentication with your backend service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExampleRegisterRequest" }, "example": {"registration_info":{"username":"auctane-next-day","password":"password!","meter_number":"8675309"},"transaction_id":"00000000-0000-0000-0000-000000000000","metadata":{"username":"auctane-next-day","password":"password!","meter_number":"8675309"}} } } }, "responses": { "200": { "description": "The Register method returns the result of the carrier's authentication process. This information will be included in the metadata of every subsequent request to your application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" }, "example": {"credentials":{"username":"auctane-next-day","password":"password!"},"metadata":{"username":"auctane-next-day","password":"password!","meter_number":"8675309"}} } } } } } }, "/CreateLabel": { "post": { "tags": [ "Labels" ], "description": "This method creates a new label.", "operationId": "CreateLabel", "parameters": [ { "name": "transactionId", "in": "query", "description": "The transaction ID uniquely represents this request.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "An object containing information about the new label to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful create label request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelResponse" } } } } } } }, "/VoidLabels": { "post": { "tags": [ "Labels" ], "description": "This method is used to void a previously created labels.", "operationId": "VoidLabels", "requestBody": { "description": "An object containing information about the labels to void.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidLabelsRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful void labels request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidLabelsResponse" } } } } } } }, "/CreateManifest": { "post": { "tags": [ "Manifesting" ], "description": "This method creates an end-of-day manifest and should be implemented by carrier apps that support\r\nend-of-day manifesting.", "operationId": "CreateManifest", "requestBody": { "description": "An object containing information about the labels to manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManifestRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful create manifest request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManifestResponse" } } } } } } }, "/GetManifest": { "post": { "tags": [ "Manifesting" ], "description": "This method retrieves the end-of-day manifest created by an earlier create manifest call.\r\nThe CreateManifestRequestId returned in the CreateManifest, is used to find the manifest.", "operationId": "GetManifest", "requestBody": { "description": "An object containing information about the manifest request that is in progress to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManifestRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful create manifest request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManifestResponse" } } } } } } }, "/ValidateInboundData": { "post": { "tags": [ "Normalize Inbound Data" ], "description": "This method validates and then returns the type of information contained in the inbound data,\r\nsuch as tracking information\r\n \r\nCarriers which support webhook based tracking or manifesting updates may choose to implement this endpoint\r\n \r\nNote: Changes made to the connection meta-data will not be saved if modified", "operationId": "ValidateInboundData", "requestBody": { "description": "An object containing information sent by the carrier via an inbound data request (e.g. a webhook).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInboundDataRequest" }, "example": {"data":"{\"tracking_number\":\"12345678901234567890\",\"status\":11,\"timestamp\":\"2021-08-11T21:15:00Z\"}","headers":{"content-type":["application/json"],"X-Signature":["v1:cedff7d0389299089e4c62c1042ce93059664d455ed0bfdf29cb959a861bda4b","v2:4b3157c730e498cb1126359fa020017e9e7c97b148f2d55da822fdfcd83e4a19"]},"transaction_id":"00000000-0000-0000-0000-000000000000","metadata":{"username":"auctane-next-day","password":"password!","meter_number":"8675309"}} } } }, "responses": { "200": { "description": "An object with a list of information contained in the inbound data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInboundDataResponse" }, "examples": { "Tracking": { "summary": "Tracking", "value": {"content_types":["tracking"]} } } } } } } } }, "/NormalizeTrackingData": { "post": { "tags": [ "Normalize Inbound Data" ], "description": "This method returns normalized tracking information for one or more shipments based on data send by the carrier\r\n \r\nCarriers which support webhook based tracking updates may choose to implement this endpoint\r\n \r\nNote: Changes made to the connection meta-data will not be saved if modified", "operationId": "NormalizeTrackingData", "requestBody": { "description": "An object containing tracking information sent by the carrier via an inbound data request (e.g. a webhook).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizeTrackingDataRequest" }, "example": {"data":"{\"tracking_number\":\"12345678901234567890\",\"status\":11,\"timestamp\":\"2021-08-11T21:15:00Z\"}","headers":{"content-type":["application/json"],"X-Signature":["v1:cedff7d0389299089e4c62c1042ce93059664d455ed0bfdf29cb959a861bda4b","v2:4b3157c730e498cb1126359fa020017e9e7c97b148f2d55da822fdfcd83e4a19"]},"transaction_id":"00000000-0000-0000-0000-000000000000","metadata":{"username":"auctane-next-day","password":"password!","meter_number":"8675309"}} } } }, "responses": { "200": { "description": "An object with tracking information for one or more shipments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizeTrackingDataResponse" }, "examples": { "Delivered": { "summary": "Delivered", "value": {"tracking_info":[{"carrier_name":"UPS","tracking_number":"12345678901234567890","standardized_status_code":"DE","carrier_status_code":"11","carrier_status_description":"Delivered","estimated_delivery_datetime":"2021-08-11T00:00:00","actual_delivery_datetime":"2021-08-11T21:15:00Z","service":{"code":"03","name":"UPS® Ground"},"packaging":"package","package_count":1,"shipping_problem":false,"carrierEnum":0}],"update_method":"append"} } } } } } } } }, "/CreateNotification": { "post": { "tags": [ "Shipment Notifications" ], "operationId": "CreateNotification", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful create notification request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationResponse" } } } } } } }, "/CancelNotification": { "post": { "tags": [ "Shipment Notifications" ], "operationId": "CancelNotification", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelNotificationRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful cancel notification request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelNotificationResponse" } } } } } } }, "/SchedulePickup": { "post": { "tags": [ "Scheduled Pickups" ], "description": "This method is used to schedule a pickup with a carrier.", "operationId": "SchedulePickup", "requestBody": { "description": "An object containing information about the pickup being scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulePickupRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful schedule pickup request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulePickupResponse" } } } } } } }, "/CancelPickup": { "post": { "tags": [ "Scheduled Pickups" ], "operationId": "CancelPickup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPickupRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful cancel pickup request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPickupResponse" } } } } } } }, "/GetRates": { "post": { "tags": [ "Rating" ], "description": "This method calculates the shipping costs for a shipment, or multiple permutations of a shipment, to allow\r\nyour customers to select the best rate.\r\n \r\nMost carrier apps should implement this method, unless you don't support rating shipments.", "operationId": "GetRates", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRatesRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful get rates request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRatesResponse" } } } } } } }, "/GetRelayPoints": { "post": { "tags": [ "Relay Points" ], "description": "This method gets carrier relay points based on search criteria.", "operationId": "GetRelayPoints", "parameters": [ { "name": "transactionId", "in": "query", "description": "The transaction ID uniquely represents this request.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "An object containing search criteria for relay points.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelayPointsRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful get relay points request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelayPointsResponse" } } } } } } }, "/GetServicePoints": { "post": { "tags": [ "Service Points" ], "description": "This method gets carrier service points based on search criteria.", "operationId": "Get Service Points", "parameters": [ { "name": "ShipStation-TransactionID", "in": "header", "description": "The transaction ID uniquely represents this request.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "An object containing search criteria for service points.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetServicePointsRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful get service points response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetServicePointsResponse" } } } } } } }, "/GetServicePoint": { "post": { "tags": [ "Service Points" ], "description": "This method gets a carrier service point by id", "operationId": "Get Service Point", "parameters": [ { "name": "ShipStation-TransactionID", "in": "header", "description": "The transaction ID uniquely represents this request.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "An object containing search criteria for service points.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetServicePointRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful get service point response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetServicePointResponse" } } } } } } }, "/Track": { "post": { "tags": [ "Tracking" ], "description": "This method returns tracking information for a shipment, including each of the tracking events that\r\nhave occurred for the shipment.\r\n \r\nMost carrier applications should implement this method, unless you don't support tracking shipments.", "operationId": "Track", "requestBody": { "description": "An object containing information about the label to track.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingRequest" }, "example": {"tracking_number":"12345678901234567890","is_return":false,"identifiers":[{"type":"tracking_number","value":"12345678901234567890"},{"type":"carrier_transaction_id","value":"US-12345678901234567890-1"}],"attributes":[{"type":"marketplace_order_token","value":"123456abcdefg7890"}],"transaction_id":"00000000-0000-0000-0000-000000000000","metadata":{"username":"auctane-next-day","password":"password!","meter_number":"8675309"}} } } }, "responses": { "200": { "description": "An object with tracking information for the specified shipment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResponse" }, "examples": { "Delivered with Event History": { "summary": "Delivered with Event History", "value": {"tracking_info":{"carrier_name":"UPS","tracking_number":"12345678901234567890","standardized_status_code":"DE","carrier_status_code":"D","carrier_detail_code":"FS","carrier_status_description":"Delivered","estimated_delivery_datetime":"2021-08-11T00:00:00","actual_delivery_datetime":"2021-08-11T21:15:00Z","weight":500.0,"dimensions":{"length":10.0,"width":10.0,"height":10.0},"service":{"code":"03","name":"UPS® Ground"},"packaging":"package","package_count":1,"events":[{"event_datetime":"2021-08-08T21:15:00Z","event_datetime_local":"2021-08-08T16:15:00","event_code":"M","carrier_detail_code":"DP","description":"Order Processed: Ready for UPS","city":"Austin","state":"TX","postal_code":"78756","country":"US","geo":{"lat":30.31,"long":-97.74},"status_code":"AC"},{"event_datetime":"2021-08-09T09:15:00Z","event_datetime_local":"2021-08-09T04:15:00","event_code":"I","carrier_detail_code":"MY","description":"In Transit","city":"Austin","state":"TX","postal_code":"78756","country":"US","geo":{"lat":30.2,"long":-97.66},"status_code":"IT"},{"event_datetime":"2021-08-10T09:15:00Z","event_datetime_local":"2021-08-10T04:15:00","event_code":"I","carrier_detail_code":"DS","description":"On Vehicle for Delivery","city":"Los Angeles","state":"CA","postal_code":"90045","country":"US","geo":{"lat":33.95,"long":-118.38},"status_code":"IT"},{"event_datetime":"2021-08-10T15:15:00Z","event_datetime_local":"2021-08-10T10:15:00","event_code":"I","carrier_detail_code":"OF","description":"On Vehicle for Delivery Today","city":"Los Angeles","state":"CA","postal_code":"90045","country":"US","geo":{"lat":33.95,"long":-118.38},"status_code":"IT"},{"event_datetime":"2021-08-10T21:15:00Z","event_datetime_local":"2021-08-10T16:15:00","event_code":"I","carrier_detail_code":"QS","description":"First Attempt Made","city":"El Segundo","state":"CA","postal_code":"90245","country":"US","geo":{"lat":33.95,"long":-118.38},"status_code":"AT"},{"event_datetime":"2021-08-11T03:15:00Z","event_datetime_local":"2021-08-10T22:15:00","event_code":"I","carrier_detail_code":"OF","description":"On Vehicle for Delivery Today","city":"Los Angeles","state":"CA","postal_code":"90045","country":"US","geo":{"lat":33.95,"long":-118.38},"status_code":"IT"},{"event_datetime":"2021-08-11T21:15:00Z","event_datetime_local":"2021-08-11T16:15:00","event_code":"D","carrier_detail_code":"FS","description":"Delivered","city":"El Segundo","state":"CA","postal_code":"90245","country":"US","geo":{"lat":33.95,"long":-118.38},"status_code":"DE"}],"shipping_problem":false,"carrierEnum":0}} }, "Not Yet in System": { "summary": "Not Yet in System", "value": {"tracking_info":{"carrier_name":"UPS","tracking_number":"12345678901234567890","standardized_status_code":"NY","events":[],"shipping_problem":false,"carrierEnum":0}} }, "Fatal Exception": { "summary": "Fatal Exception", "value": {"tracking_info":{"carrier_name":"UPS","tracking_number":"12345678901234567890","standardized_status_code":"EX","carrier_status_code":"X","carrier_detail_code":"KR","carrier_status_description":"Delivery Refused","estimated_delivery_datetime":"2021-08-11T00:00:00","actual_delivery_datetime":"2021-08-11T21:15:00Z","weight":500.0,"dimensions":{"length":10.0,"width":10.0,"height":10.0},"service":{"code":"03","name":"UPS® Ground"},"packaging":"package","package_count":1,"events":[{"event_datetime":"2021-08-09T09:15:00Z","event_datetime_local":"2021-08-09T04:15:00","event_code":"I","carrier_detail_code":"MY","description":"In Transit","city":"Austin","state":"TX","postal_code":"78756","country":"US","geo":{"lat":30.2,"long":-97.66},"status_code":"IT"},{"event_datetime":"2021-08-11T21:15:00Z","event_datetime_local":"2021-08-11T16:15:00","event_code":"X","carrier_detail_code":"KR","description":"Delivery Refused","city":"El Segundo","state":"CA","postal_code":"90245","country":"US","geo":{"lat":33.95,"long":-118.38},"status_code":"EX"}],"shipping_problem":false,"carrierEnum":0}} } } } } } } } }, "/ImportTrackingEvents": { "post": { "tags": [ "Tracking" ], "description": "This method should yield imported tracking events for a connection. It should\r\nonly be implemented if you support importing tracking data in bulk via file\r\nexchange or API requests.\r\nAny information needed to retrieve tracking data for a connection should be\r\ncollected in your registration form and will be made available as metadata in\r\nthe request.\r\nSee the [Tracking Overview](https://connect.shipengine.com/shipping/tracking/)\r\nfor implementation details.", "operationId": "ImportTrackingEvents", "requestBody": { "description": "An object containing information about the connection to import tracking events for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTrackingEventsRequest" } } } }, "responses": { "200": { "description": "A list of imported tracking events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImportedTrackingEvent" } } } } } } } }, "/UpdateSettings": { "post": { "tags": [ "Account Setup" ], "description": "This method is used to update carrier settings.", "operationId": "Update Settings", "requestBody": { "description": "An object containing the settings information that you wish to be updated for a given carrier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsRequest" } } } }, "responses": { "200": { "description": "The Update Settings method updates carrier settings that were set up during the registration of a given carrier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsResponse" } } } } } } }, "/ValidateShipment": { "post": { "tags": [ "Validations" ], "description": "This method validates a shipment against carrier constraints for selected service.", "operationId": "ValidateShipment", "requestBody": { "description": "An object containing information about the shipment and selected services to validate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateShipmentRequest" } } } }, "responses": { "200": { "description": "This object model represents the response from a successful validate shipment request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateShipmentResponse" } } } } } } } }, "components": { "schemas": { "AccessibilityTypes": { "enum": [ "accessible", "inaccessible" ], "type": "string", "description": "Specifies if the product is accessible during delivery,\r\naccessible\r\ninaccessible" }, "AddressBase": { "required": [ "postal_code", "country_code" ], "type": "object", "properties": { "address_lines": { "type": "array", "items": { "type": "string" }, "description": "The address lines of the address.", "nullable": true }, "city_locality": { "type": "string", "description": "The city or locality of the address, where applicable.", "nullable": true }, "state_province": { "type": "string", "description": "The state or province of the address, where applicable.", "nullable": true }, "postal_code": { "type": "string", "description": "The postal code of the address.", "nullable": true }, "country_code": { "type": "string", "description": "The two character country code of the shipment address. The codes are specified by ISO 3166-1 alpha-2.", "nullable": true } }, "additionalProperties": false }, "AddressResidentialIndicator": { "enum": [ "unknown", "yes", "no", "commercial", "residential" ], "type": "string", "description": "'Commercial' is no longer used, please use 'No'. <br />'Residential' is no longer used, please use 'Yes'." }, "AddressWithContact": { "required": [ "postal_code", "country_code" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressBase" } ], "properties": { "name": { "type": "string", "description": "The full name of the contact associated with the address", "nullable": true }, "first_name": { "type": "string", "description": "The first name of the contact associated with the address", "nullable": true }, "last_name": { "type": "string", "description": "The last name of the contact associated with the address", "nullable": true }, "email": { "type": "string", "description": "The email of the contact associated with the address", "nullable": true }, "phone_number": { "type": "string", "description": "The phone number of the contact associated with the address", "nullable": true }, "company_name": { "type": "string", "description": "The name of the company associated with this address.", "nullable": true }, "address_residential_indicator": { "$ref": "#/components/schemas/AddressResidentialIndicator" }, "instructions": { "type": "string", "description": "Instructions to help the carrier navigate to the address.", "nullable": true }, "address_metadata": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Additional metadata provided for specific requests.", "nullable": true } }, "additionalProperties": false }, "AdvancedOptions": { "type": "object", "properties": { "contains_alcohol": { "type": "boolean", "description": "Describes whether or not the shipment contains alcohol." }, "no_postage": { "type": "boolean", "description": "Describes whether no postage is necessary" }, "nonmachineable": { "type": "boolean", "description": "Describes whether or not the shipment is non automatically sortable with machines." }, "saturday_delivery": { "type": "boolean", "description": "Describes whether or not the shipment is requested to be delivered on a Saturday." }, "tip": { "required": [ "currency", "amount" ], "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal currency value, as a string." }, "currency": { "type": "string", "description": "Alpha-3 currency code complying with ISO 4217." } }, "description": "Amount to be paid to the driver, used for local delivery and courier services.", "nullable": true }, "additional_handling": { "type": "boolean", "description": "Describes whether Additional Handling is requested for the shipment." }, "collect_on_delivery": { "$ref": "#/components/schemas/CollectOnDelivery" }, "own_document_upload": { "type": "boolean", "description": "Whether client is requesting the ability to upload documents like commercial invoice after the shipment has been processed." }, "dangerous_goods": { "type": "boolean", "description": "Indicates if the Dangerous goods are present in the shipment." }, "dangerous_goods_contact": { "$ref": "#/components/schemas/DangerousGoodsContact" }, "limited_quantity": { "type": "boolean", "description": "Describes the transport of dangerous goods that is restricted to Limited Quantities of Dangerous Goods only." }, "event_notification": { "type": "boolean", "description": "Indicates whether the recipient should be notified of events related to the shipment." }, "windsor_framework_details": { "$ref": "#/components/schemas/WindsorFrameworkDetails" }, "accessibility": { "$ref": "#/components/schemas/AccessibilityTypes" }, "signatory": { "$ref": "#/components/schemas/Signatory" }, "regulation_level": { "$ref": "#/components/schemas/RegulationLevelEnum" }, "transport_mean": { "$ref": "#/components/schemas/TransportMeanEnum" } }, "additionalProperties": { }, "description": "This is a schemaless object. It is for open ended customizations unique to particular carriers. The documented\r\nkeys are some common options shared by many carriers, but are not definitive. Advanced options you support will\r\nbe defined in ShipEngine. If the field is absent it should be interpreted as the default value for any\r\napplicable options, e.g. false for booleans." }, "Authorization": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token used to authorize the request", "nullable": true }, "connection_context": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Optional - any additional information required to authorize the request", "nullable": true } }, "additionalProperties": false }, "BaseRequest": { "required": [ "transaction_id" ], "type": "object", "properties": { "transaction_id": { "type": "string", "description": "The transaction ID uniquely represents this request. If the request is retried then this transaction ID will be the same. You should only perform the requested action once per given transaction ID.", "format": "uuid" }, "authorization": { "$ref": "#/components/schemas/Authorization" }, "metadata": { "type": "object", "additionalProperties": { "type": "object", "nullable": true }, "nullable": true }, "connection_name": { "type": "string", "description": "The name of the connection to use, if this app has connection names defined", "nullable": true } }, "additionalProperties": false }, "BaseResponse": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "This is an optional schemaless object that you may return with a successful response. Anything returned\r\nunder this key will be included in all future requests. For example, you may store additional static\r\nproperties about the end user or their connection to the carrier. The maximum storage size\r\nfor data under this key is 4KB.", "nullable": true } }, "additionalProperties": false }, "BillTo": { "required": [ "postal_code", "country_code" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/AddressWithContact" } ], "properties": { "bill_to_party": { "$ref": "#/components/schemas/BillToParty" }, "account_number": { "type": "string", "description": "Specified if there is an account number associated with the Bill To Party, and the Bill To Party is\r\nnot the account holder.", "nullable": true } }, "additionalProperties": false, "description": "Bill to is a generic object used for billing a part of the shipment, duties, taxes, or otherwise to a party\r\nother than the shipper (the shipper is considered the default party responsible). CarrierApi.Common.Request.CarrierApi.Common.Models.BillTo\r\nextends CarrierApi.Common.Models.Addresses.AddressWithContact since address fields are often required when associating billing to\r\nanother account. Additionally, this allows for a contact to be specified, if necessary." }, "BillToParty": { "enum": [ "shipper", "recipient", "third_party_account" ], "type": "string", "description": "The type of party responsible for a given category of charges associated with a shipment, such as shipping charges or import duties." }, "BillingCategories": { "enum": [ "uncategorized", "shipping", "insurance", "confirm", "discount", "fuel_charge", "additional_fees", "tariff", "tax", "delivery", "handling", "special_goods", "pickup", "location_fee", "oversize", "returns", "notifications", "tip", "duties_and_taxes", "brokerage_fee" ], "type": "string" }, "BillingLineItem": { "required": [ "billing_category", "amount" ], "type": "object", "properties": { "billing_category": { "$ref": "#/components/schemas/BillingCategories" }, "carrier_description": { "type": "string", "description": "If the carrier provides a description from their API about the billing charge (not specific to the user). Maximum length of 100 characters.", "nullable": true }, "carrier_billing_code": { "type": "string", "description": "If the carrier provides a billing code for", "nullable": true }, "memo": { "type": "string", "description": "This will often be empty; however, if there was additionally specific information about the charge it should go here, could also be a reference number. Maximum length of 250 characters.", "nullable": true }, "amount": { "required": [ "currency", "amount" ], "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal currency value, as a string." }, "currency": { "type": "string", "description": "Alpha-3 currency code complying with ISO 4217." } }, "description": "Total amount of the line item to be billed to the end customer.", "nullable": true }, "tax_details": { "$ref": "#/components/schemas/TaxDetails" } }, "additionalProperties": false }, "CancelNotificationRequest": { "required": [ "transaction_id" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ], "properties": { "notification_id": { "type": "string", "description": "The id of the notification.", "nullable": true }, "shipment_information": { "$ref": "#/components/schemas/ShippedShipment" } }, "additionalProperties": false, "description": "A request to cancel the pending notification of a shipment." }, "CancelNotificationResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" } ], "properties": { "message": { "type": "string", "description": "User facing text describing the cancellation process. May be left \r\nblank to present a default value.", "nullable": true }, "errors": { "type": "array", "items": { "type": "string" }, "description": "A list of errors preventing this notification from being cancelled.\r\nIf no errors are returned the void is considered successful. If \r\nany errors are returned the void is considered failed.", "nullable": true } }, "additionalProperties": false, "description": "The response to the cancellation of a pending shipment notification." }, "CancelPickupRequest": { "required": [ "pickup_windows", "transaction_id" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ], "properties": { "confirmation": { "$ref": "#/components/schemas/PickupConfirmation" }, "location": { "$ref": "#/components/schemas/PickupLocationDetails" }, "cancellation_details": { "$ref": "#/components/schemas/CancellationDetails" }, "contact": { "$ref": "#/components/schemas/PickupContactDetails" }, "pickup_details": { "$ref": "#/components/schemas/PickupShipmentDetails" }, "pickup_windows": { "type": "array", "items": { "$ref": "#/components/schemas/PickupWindow" }, "description": "The time windows that the carrier returned in the Schedule Pickup Response", "nullable": true }, "custom_properties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "The grab bag of properties necessary to cancel the pickup", "nullable": true } }, "additionalProperties": false, "description": "A request to cancel a previously scheduled pickup" }, "CancelPickupResponse": { "required": [ "successful" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponse" } ], "properties": { "confirmation_id": { "type": "string", "description": "The confirmation id from the carrier associated with the cancellation request", "nullable": true }, "successful": { "type": "boolean", "description": "A flag for whether or not the cancellation was successful" }, "status": { "type": "string", "description": "The optional status returned by the carrier", "nullable": true, "example": "Your pickup was cancelled. Unable to cancel over the network, please call ### ### ####." }, "custom_properties": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "A grab bag used to store additional information that might be useful for logging or internal reporting.", "nullable": true } }, "additionalProperties": false, "description": "This model represents a response for a successful cancel pickup request." }, "CancellationDetails": { "required": [ "reason" ], "type": "object", "properties": { "reason": { "$ref": "#/components/schemas/CancellationReason" }, "cancellation_options": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Additional properties about the cancellation", "nullable": true }, "remarks": { "type": "string", "description": "Remarks about why the customer is cancelling the pickup", "nullable": true } }, "additionalProperties": false, "description": "This model contains the explanation of why a user is cancelling a pickup." }, "CancellationReason": { "enum": [ "other", "not_ready", "cost_too_high", "service_too_slow", "carrier_failed_pickup" ], "type": "string", "description": "An enumeration of common reasons cancellations occur" }, "CarrierWeight": { "type": "object", "properties": { "value": { "type": "number", "description": "The actual weight value assessed by the carrier based on the ingredients provided, it may be used for customer billing purposes.", "format": "double" }, "unit": { "$ref": "#/components/schemas/WeightUnit" } }, "additionalProperties": false }, "CodPaymentType": { "enum": [ "any", "cash", "guaranteed_funds" ], "type": "string", "description": "Specifies which payment method is permitted when Collect on Delivery (COD) is requested on a shipment.\r\nany - Any payment method is permitted.\r\ncash - Only cash is permitted.\r\nguaranteed_funds - Only guaranteed funds are permitted, such as a money order or cashier's check." }, "CollectOnDelivery": { "required": [ "payment_amount" ], "type": "object", "properties": { "payment_amount": { "required": [ "currency", "amount" ], "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal currency value, as a string." }, "currency": { "type": "string", "description": "Alpha-3 currency code complying with ISO 4217." } }, "description": "The payment amount for Collect on Delivery (COD).", "nullable": true }, "payment_type": { "$ref": "#/components/schemas/CodPaymentType" } }, "additionalProperties": false, "description": "This model represents the option to defer payment for a shipment, otherwise known as Collect on Delivery (COD)." }, "ConfirmationTypes": { "enum": [ "None", "Delivery", "Signature", "AdultSignature", "DirectSignature" ], "type": "string" }, "CreateLabelRequest": { "required": [ "service_code", "ship_datetime", "is_return_label", "is_residential", "packages",