Skip to content
MothershipDevelopers

API referenceShipments

Cancel a shipment

Attempts to cancel the shipment immediately. By default, the request succeeds only when the cancellation path available right now is free. To accept a paid cancellation, set acceptFees, and optionally cap the fee with limitAmountCents.

POST/shipments/{shipmentId}/cancel
Environment
https://sandbox.api.mothership.com/beta
curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/shipments/MS5016101/cancel' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "ShipmentNotNeeded",
  "acceptFees": true,
  "limitAmountCents": 5000
}'
Reads your token from $MOTHERSHIP_API_TOKEN
Response
{
: {
: "cancelled",
: 0
}
}

Hover a key to see what it means. Click it to jump to the field.

Cancellation is immediate. The request only succeeds when cancelling is free, unless you set acceptFees to true. With acceptFees, add limitAmountCents to cap the fee you'll pay. A successful cancellation returns the fee charged in cancellationFeeCents.

ResponseWhen
200The shipment was cancelled.
402 PAYMENT_REQUIREDCancelling costs more than you accepted. metadata.feeCents is the lowest fee available, and metadata.availableCancellationOptions lists each option's type and feeCents. Retry with acceptFees: true and a high enough limitAmountCents.
409 INVALID_REQUEST"This shipment cannot be cancelled at this time." For example, a cancellation is already in progress.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Path parameters

  • shipmentIdstringRequired

    Reference number of the shipment to cancel

Request body

application/json · required
  • reasonstringRequired

    Reason for cancellation.

    CargoNotReadyShipmentCorrectionsNeededIncorrectCargoInfoMissingAccessorialShipmentNotNeeded
  • acceptFeesboolean

    When true, cancels the shipment even if the cancellation path available now has a fee. Defaults to false.

    Defaults to false
  • limitAmountCentsinteger

    The most you will pay for the cancellation, in cents, when acceptFees is true. Optional.

    min 0

Responses

    • dataobjectRequired
      • statusstringRequired

        Whether the cancellation completed successfully

        cancelled
      • cancellationFeeCentsintegerRequired

        Fee in cents associated with the completed cancellation

        min 0

What's next

GETList a shipment's invoices

Check the shipment’s invoices, which can include a cancellation-fee line item.