POST/shipment/{shipmentId}/cancel
This method cancels the shipment associated with the specified shipment ID and the associated shipping label is deleted. When you cancel a shipment, the totalShippingCost of the canceled shipment is refunded to the account established by the user's billing agreement.
Note that you cannot cancel a shipment if you have used the associated shipping label.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| shipmentId | string | This path parameter specifies the unique eBay-assigned ID of the shipment to be canceled. The shipmentId value is generated and returned by the createFromShippingQuote method. Occurrence: Required |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.logistics
See OAuth access tokens for more information.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| cancellation | ShipmentCancellation | Cancellation status for the package, if one exists. Occurrence: Conditional |
| cancellation.cancellationRequestedDate | string | The time and date the request was made to cancel the shipment, formatted as an ISO 8601 UTC string. Occurrence: Conditional |
| cancellation.cancellationStatus | ShipmentCancellationStatusEnum | This enum specifies the current cancellation status of a shipment, if a cancellation request has been made. Occurrence: Conditional |
| creationDate | string | The date and time the shipment was created, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Occurrence: Conditional |
| labelCustomMessage | string | If supported by the selected shipping carrier, this field can contain optional seller text to be printed on the shipping label. Occurrence: Conditional |
| labelDownloadUrl | string | The direct URL the seller can use to download an image of the shipping label. By default, the file format is PDF. See downloadLabelFile for requesting different response file formats. Occurrence: Conditional |
| labelSize | string | The seller's desired label size. The support for multi-sized labels is shipping-carrier specific and if the size requested in the creaateFromShippingQuote call matches a size the carrier supports, the value will be represented here in the shipment. Occurrence: Conditional |
| orders | array of Order | A list of one or more orders that will be shipped in the shipping package. Occurrence: Always |
| orders.channel | string | The marketplace where the order was created. Occurrence: Always |
| orders.orderId | string | The unique identifier of the order. The getOrders method of the Fulfillment API can be used to retrieve order IDs. Occurrence: Always |
| packageSpecification | PackageSpecification | The weight and dimensions of the package. Occurrence: Conditional |
| packageSpecification.dimensions | Dimensions | Declares the height, length, width, and unit of measure for the package to be shipped. Occurrence: Conditional |
| packageSpecification.dimensions.height | string | The numeric value of the height of the package. Occurrence: Conditional |
| packageSpecification.dimensions.length | string | The numeric value of the length of the package. Occurrence: Conditional |
| packageSpecification.dimensions.unit | LengthUnitOfMeasureEnum | The unit of measure used to express the height, length, and width of the package. Occurrence: Conditional |
| packageSpecification.dimensions.width | string | The numeric value of the width of the package. Occurrence: Conditional |
| packageSpecification.weight | Weight | Declares the weight of the package. Occurrence: Conditional |
| packageSpecification.weight.unit | WeightUnitOfMeasureEnum | The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are Occurrence: Conditional |
| packageSpecification.weight.value | string | The numeric value of the weight of the package, as measured by the value of unit. Occurrence: Conditional |
| rate | PurchasedRate | The shipping rate that the seller has chosen to purchase for this shipment. Each rate, identified by a rateId, contains the offered base service, options, and shipping parameters that were selected for the package shipment. Occurrence: Conditional |
| rate.additionalOptions | array of AdditionalOption | An list of additional, optional features that have been purchased for the shipment. Occurrence: Conditional |
| rate.additionalOptions.additionalCost | Amount | The monetary cost of the additional shipping option identified by the optionType field. Occurrence: Conditional |
| rate.additionalOptions.additionalCost.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| rate.additionalOptions.additionalCost.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| rate.additionalOptions.optionType | string | The name of a shipping option that can be purchased in addition to the base shipping cost of this rate. The value supplied in this field must match exactly the option name as supplied by the selected rate. Occurrence: Conditional |
| rate.baseShippingCost | Amount | The amount of the "base cost" for the shipment as set by the given carrier for the specified service. This cost excludes any addition costs accrued from the addition of any optional shipping options. Occurrence: Conditional |
| rate.baseShippingCost.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| rate.baseShippingCost.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| rate.destinationTimeZone | string | The time zone of the destination according to Time Zone Database. For example, "America/Los_Angeles". Occurrence: Conditional |
| rate.maxEstimatedDeliveryDate | string | A string value representing maximum (latest) estimated delivery time, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Occurrence: Conditional |
| rate.minEstimatedDeliveryDate | string | A string value representing minimum (earliest) estimated delivery time, formatted as an ISO 8601ISO 8601 UTC string. Occurrence: Conditional |
| rate.pickupNetworks | array of string | A list of pickup networks compatible with the shipping service. Occurrence: Conditional |
| rate.pickupSlotId | string | This unique eBay-assigned ID value is returned only if the shipment has been configured for a scheduled pickup. Occurrence: Conditional |
| rate.pickupType | PickupTypeEnum | The type of pickup or drop off configured for the shipment. Occurrence: Conditional |
| rate.rateId | string | The eBay-generated ID of the shipping rate that the seller has chosen to purchase for the shipment. Occurrence: Conditional |
| rate.shippingCarrierCode | string | The ID code for the carrier that was selected for the package shipment. Occurrence: Conditional |
| rate.shippingCarrierName | string | The name of the shipping carrier. Occurrence: Conditional |
| rate.shippingQuoteId | string | The unique eBay-generated ID of the shipping quote from which the seller selected a shipping rate (rateId). Occurrence: Conditional |
| rate.shippingServiceCode | string | String ID code for the shipping service selected for the package shipment. This is a service that the shipping carrier supplies. Occurrence: Conditional |
| rate.shippingServiceName | string | The name of the shipping service. Occurrence: Conditional |
| rate.totalShippingCost | Amount | The total shipping cost, which is the sum cost of the base shipping cost and the cost of all the selected shipping options. Occurrence: Conditional |
| rate.totalShippingCost.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| rate.totalShippingCost.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| returnTo | Contact | The address and contact details that should be used for item returns. Sellers have the option to define a return address that is different from their shipFrom address. If not specified, the return address defaults to the shipFrom address in the shipping quote. Occurrence: Conditional |
| returnTo.companyName | string | The company name with which the contact is associated. Occurrence: Conditional |
| returnTo.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Conditional |
| returnTo.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Always |
| returnTo.contactAddress.addressLine2 | string | The second line of the street address. Use this field for additional address information, such as a suite or apartment number. Occurrence: Conditional |
| returnTo.contactAddress.city | string | The city in which the address is located. Occurrence: Conditional |
| returnTo.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Conditional |
| returnTo.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Conditional |
| returnTo.contactAddress.postalCode | string | The postal code of the address. Occurrence: Always |
| returnTo.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Conditional |
| returnTo.fullName | string | The contact's full name. Occurrence: Conditional |
| returnTo.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Conditional |
| returnTo.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Conditional |
| shipFrom | Contact | The address and contact details for the origin of the package shipment. Occurrence: Conditional |
| shipFrom.companyName | string | The company name with which the contact is associated. Occurrence: Conditional |
| shipFrom.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Conditional |
| shipFrom.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Always |
| shipFrom.contactAddress.addressLine2 | string | The second line of the street address. Use this field for additional address information, such as a suite or apartment number. Occurrence: Conditional |
| shipFrom.contactAddress.city | string | The city in which the address is located. Occurrence: Conditional |
| shipFrom.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Conditional |
| shipFrom.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Conditional |
| shipFrom.contactAddress.postalCode | string | The postal code of the address. Occurrence: Always |
| shipFrom.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Conditional |
| shipFrom.fullName | string | The contact's full name. Occurrence: Conditional |
| shipFrom.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Conditional |
| shipFrom.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Conditional |
| shipmentId | string | The unique eBay-assigned ID for the shipment. The ID is generated when the shipment is created by a call to createFromShippingQuote. Occurrence: Conditional |
| shipmentTrackingNumber | string | A unique carrier-assigned ID string that can be used to track the shipment. Occurrence: Conditional |
| shipTo | Contact | The address and contact details for the destination of the shipment. Occurrence: Conditional |
| shipTo.companyName | string | The company name with which the contact is associated. Occurrence: Conditional |
| shipTo.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Conditional |
| shipTo.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Always |
| shipTo.contactAddress.addressLine2 | string | The second line of the street address. Use this field for additional address information, such as a suite or apartment number. Occurrence: Conditional |
| shipTo.contactAddress.city | string | The city in which the address is located. Occurrence: Conditional |
| shipTo.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Conditional |
| shipTo.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Conditional |
| shipTo.contactAddress.postalCode | string | The postal code of the address. Occurrence: Always |
| shipTo.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Conditional |
| shipTo.fullName | string | The contact's full name. Occurrence: Conditional |
| shipTo.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Conditional |
| shipTo.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Conditional |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
| Status | Meaning |
|---|---|
| 200 | Success |
| 404 | Not Found |
| 409 | Conflict |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 90000 | API_LOGISTICS | APPLICATION | A system error has occurred. |
| 90005 | API_LOGISTICS | REQUEST | The resource could not be found. |
| 90260 | API_LOGISTICS | REQUEST | Cannot cancel shipment {shipmentId} |
Warnings
This call has no warnings.
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Cancel a shipment
This method cancels an existing shipment and refunds the totalShippingCost to the account that was billed when the shipment was created.
Input
This method does not use a request body. Supply the shipmentId as a path parameter in your request.
POSThttps://api.ebay.com/sell/logistics/v1_beta/shipment/S********1/cancel
Output
If the call is successful, an HTTP status code 200 OK is returned. The response body contains the fill details of the of the shipment that was canceled and the cancellationStatus is set to CANCELLATION_REQUESTED.