We Ship You

Shop

WeShipYou
Shop curated products from WeShipYou sellers, fulfilled end-to-end with our shipping guarantee.
Amazon
Shop on Amazon, the world's largest store with the widest range of products, all with the security of WeShipYou!
eBay
New and used items from US sellers: we buy Buy It Now listings for you.
AliExpress
Millions of products at factory prices, bought and shipped by us.
Walmart
Shop pharmacy and grocery products at Walmart quickly and easily!
Shein
Shop the latest trending products at the best discounted prices, only at the Shein store!
Temu
Shop the best products at discounted prices at the Temu store!
Shopify
Search thousands of US Shopify stores at once, or paste a link from any of them.

JavaScript Required: Enable and Reload for weshipyou.com to Function Properly

We have detected that JavaScript is currently disabled in your browser. To ensure weshipyou.com works as intended, please enable JavaScript and refresh this page. JavaScript is essential for the proper functioning and optimal user experience of our website. Thank you!

Se requiere JavaScript: habilite y vuelva a cargar para que weshipyou.com funcione correctamente

Hemos detectado que JavaScript está actualmente deshabilitado en su navegador. Para garantizar que weshipyou.com funcione según lo previsto, habilite JavaScript y actualice esta página. JavaScript es esencial para el correcto funcionamiento y la óptima experiencia de usuario de nuestro sitio web. ¡Gracias!

.NoScriptForm-content{font-family:-apple-system,system-ui,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;font-size:18px;line-height:24px;margin:10%;width:80%}.pg-loading-screen{position:fixed;inset:0;z-index:1000000;background:#fff}.pg-loading-inner{height:100%;width:100%;margin:0;padding:0;position:static}.pg-loading-center-outer{width:100%;height:100%;padding:0;margin:0;display:table!important;position:absolute;top:0;left:0}.pg-loading-center-middle{padding:0;margin:0;vertical-align:middle;display:table-cell!important;text-align:center}.pg-loading-logo-header{font-family:-apple-system,system-ui,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;width:100%;text-align:center;animation:pgAnimLoading 1s cubic-bezier(.7,0,.3,1) both}.pg-loading-html{width:100%;margin-top:90px}@keyframes pgAnimLoading{from{opacity:0}}.sk-spinner-double-bounce.sk-spinner{width:40px;height:40px;position:relative;margin:0 auto}.sk-double-bounce1,.sk-double-bounce2{width:100%;height:100%;border-radius:50%;background:#dcdcdc;opacity:.6;position:absolute;top:0;left:0;animation:sk-doubleBounce 2s infinite ease-in-out}.sk-double-bounce2{animation-delay:-1s}@keyframes sk-doubleBounce{0%,100%{transform:scale(0)}50%{transform:scale(1)}}

We Ship You

Shop

Shipments

Create, rate, label, cancel and confirm your shipments

POST/shipments/rates
GET/shipments
POST/shipments
GET/shipments/{shipmentId}
PATCH/shipments/{shipmentId}
DELETE/shipments/{shipmentId}
GET/shipments/categories
GET/shipments/country-categories
POST/shipments/labels
DELETE/shipments/labels/{trackingNumber}
POST/shipments/confirm-delivery

The Shipment object

A shipment: what is sent, from whom, to whom, and its label and delivery status.

Attributes

uidstringrequired
Shipment UID. Use it as shipmentId.
statestringrequired
Lifecycle state, from created through label_created to delivered or cancelled.
statusTrackingstringnullable
Latest carrier tracking status, in words.
transactionStatestringnullable
Billing state of the shipment, when it was charged or refunded.
externalReferenceCodestringnullable
Your own reference for the shipment.
externalCustomerIdstringnullable
Your own customer reference.
externalUniqueIdstringnullable
Your own idempotency reference.
incotermsstringrequired
Who pays duties: the recipient (DDU) or the sender (DDP).
Allowed values:DDUDDP
weightUnitstringrequired
Unit of weight.
Allowed values:gmkgozlb
dimUnitstringrequired
Unit of length, width and height.
weightnumbernullable
Total weight.
lengthnumbernullable
Length of the box.
widthnumbernullable
Width of the box.
heightnumbernullable
Height of the box.
totalValuenumbernullable
Declared value of the contents, USD.
insuranceboolean | integer
The shipment is insured. 1/true or 0/false.
insuranceAmountnumbernullable
Insured amount, USD.
appliedCouponDiscountnumbernullable
Coupon discount applied to the label price, USD.
sellerNotesstringnullable
Notes from the sender.
buyerNotesstringnullable
Notes from the recipient.
labelCreatedAtstring <date-time>nullable
When the label was bought.
deliveredAtstring <date-time>nullable
When the carrier delivered the shipment.
cancellationReasonstringnullable
Why the shipment was cancelled.
cancellationReasonCodestringnullable
Machine code of the cancellation reason.
customsAuthorizationsobject
Customs documents the destination requires, and whether the customer can still edit them.
senderobjectnullable
The sender. Included when the shipment is read on its own.
Child attributes
- uidstring
  Address book entry UID.
- nicknamestringnullable
  Your label for the entry.
- companyNamestringnullable
  Company name.
- namestringnullable
  Full name.
- taxIdstringnullable
  Tax ID.
- emailstringnullable
  Email address.
- phonestringnullable
  Phone number.
- isResidentialboolean | integer
  Residential delivery address.
- statusstring
  Entry status.
- addressobjectnullable
  A postal address as WeShipYou parsed it.
  Child attributes
  uidstring
  Address UID.
  houseNumberstringnullable
  House or building number.
  roadstringnullable
  Street name.
  unitstringnullable
  Apartment, suite or unit.
  cityobjectnullable
  Child attributes
  namestring
  City name.
  stateobjectnullable
  Child attributes
  namestring
  isoCodestringnullable
  State code.
  countryobjectnullable
  Child attributes
  isoCodestring
  namestring
  postal_codeobjectnullable
  Child attributes
  postalCodestring
recipientobjectnullable
The recipient. Included when the shipment is read on its own.
Child attributes
- uidstring
  Address book entry UID.
- nicknamestringnullable
  Your label for the entry.
- companyNamestringnullable
  Company name.
- namestringnullable
  Full name.
- taxIdstringnullable
  Tax ID.
- emailstringnullable
  Email address.
- phonestringnullable
  Phone number.
- isResidentialboolean | integer
  Residential delivery address.
- statusstring
  Entry status.
- addressobjectnullable
  A postal address as WeShipYou parsed it.
  Child attributes
  uidstring
  Address UID.
  houseNumberstringnullable
  House or building number.
  roadstringnullable
  Street name.
  unitstringnullable
  Apartment, suite or unit.
  cityobjectnullable
  Child attributes
  namestring
  City name.
  stateobjectnullable
  Child attributes
  namestring
  isoCodestringnullable
  State code.
  countryobjectnullable
  Child attributes
  isoCodestring
  namestring
  postal_codeobjectnullable
  Child attributes
  postalCodestring
parcelsarray of object
The parcels and their items. Included when the shipment is read on its own.
parcel_ratesarray of Rate
The services this shipment can be sent with and their prices. Included in the answer of POST /shipments and PATCH /shipments/{shipmentId}; pick one and buy it with POST /shipments/labels. Their totalChargePrice includes insurance (insuranceFee) even when the shipment is not insured; see the Rate object.
Child attributes
- uidstringrequired
  The rate id. Send it as rateId to POST /shipments/labels.
- serviceobject
  The shipping service.
  Child attributes
  uidstringnullable
  The service uid.
  namestringnullable
  The service name.
  umbrellaNamestringnullable
  The carrier or brand the service belongs to.
  serviceTypestringnullable
  ground, air or sea.
- totalChargePricenumber
  The quoted price. Includes insuranceFee whether or not the shipment is insured, and improvedFoamProtectionFee. Subtract insuranceFee when the shipment is not insured.
- insuranceFeenumber
  The price of insuring the shipment with this service. It is already inside totalChargePrice; it is charged only when the shipment is insured.
- improvedFoamProtectionFeenumber
  The price of improved foam protection, already inside totalChargePrice. 0 unless the shipment asks for it.
- shipmentChargeTotalPricenumber
  The price of the shipping service alone; coupon discounts are calculated on it. It is not what the label costs: see totalChargePrice.
- pickupFeenumber
  Added to the label price when the parcels are picked up.
- minimumPickupFeenumber
  Added to the label price when the parcels are picked up.
labelobjectnullable
The label, once it is bought. Included when the shipment is read on its own (GET /shipments/{shipmentId}).
Child attributes
- trackingNumberstringnullable
  The WeShipYou tracking number (WSY…). Use it with GET /tracking/{trackingNumber} and to cancel the label.
createdAtstring <date-time>required
When the shipment was created.
updatedAtstring <date-time>required
When the shipment last changed.

The Shipment object

{
  "uid": "wwbvygom0rlz",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "shp1x6",
  "externalCustomerId": null,
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 1000,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 10,
  "insurance": 0,
  "insuranceAmount": null,
  "appliedCouponDiscount": 0,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "customsAuthorizations": {
    "required": [],
    "mincomDocumentsCount": 0,
    "canCustomerEdit": true,
    "recipientAuthorization": "optional",
    "recipientAuthorizationDocumentsCount": 0,
    "canCustomerEditRecipientAuthorization": true
  },
  "createdAt": "2026-11-01T00:37:50.000Z",
  "updatedAt": "2026-11-01T00:37:50.000Z"
}

The Category object

A shipment content category. Each parcel item declares one.

Attributes

uidstringrequired
Category UID.
namestringrequired
Display name.
slugstringrequired
Stable machine name.
weightnumbernullable
Default weight for one unit, in grams.
lengthnumbernullable
Default length, in centimeters.
widthnumbernullable
Default width, in centimeters.
heightnumbernullable
Default height, in centimeters.
containsDocumentsboolean | integer
Items in this category are documents. 1/true or 0/false.
containsOtherDgboolean | integer
Items in this category are dangerous goods other than batteries. 1/true or 0/false.
containsLiquidsboolean | integer
Items in this category contain liquids. 1/true or 0/false.
containsBatteryPi967boolean | integer
Lithium-ion batteries contained in equipment (PI 967). 1/true or 0/false.
containsBatteryPi966boolean | integer
Lithium-ion batteries packed with equipment (PI 966). 1/true or 0/false.
containsBatteryPi965boolean | integer
Lithium-ion batteries on their own (PI 965). 1/true or 0/false.
parentIdintegernullable
Parent category, when this is a sub-category.

The Category object

{
  "uid": "u40h56jccmdi",
  "name": "Phone Accessory (no battery)",
  "slug": "accessory_no_battery",
  "weight": null,
  "length": null,
  "width": null,
  "height": null,
  "containsDocuments": 0,
  "containsOtherDg": 0,
  "containsLiquids": 0,
  "containsBatteryPi967": 0,
  "containsBatteryPi966": 0,
  "containsBatteryPi965": 0,
  "parentId": null
}

The Country category object

Attributes

uidstringnullable
namestringnullable
slugstringnullable
weightnumbernullable
lengthnumbernullable
widthnumbernullable
heightnumbernullable
containsDocumentsbooleannullable
containsOtherDgbooleannullable
containsLiquidsbooleannullable
containsBatteryPi967booleannullable
containsBatteryPi966booleannullable
containsBatteryPi965booleannullable
customsValuenumbernullable
qtynumbernullable
maxWeightnumbernullable
unitTypestringnullable
observationsstringnullable
isDiscontinuedbooleannullable
createdAtstring <date-time>nullable
updatedAtstring <date-time>nullable
parentIdnumbernullable

The Rate object

A service the shipment can be sent with, and its price in USD.

totalChargePrice always includes the insurance price (insuranceFee), even when the shipment is not insured. Shipments are not insured unless you ask (insurance: true), so in most cases subtract insuranceFee to get what the label costs:

label price = totalChargePrice − insuranceFee when the shipment is not insured, or totalChargePrice when it is;
plus pickupFee and minimumPickupFee when the parcels are picked up (handoverOption: "pickup" in POST /shipments/labels).

A coupon lowers that price further.

Attributes

uidstring
The rate id. Send it as rateId to POST /shipments/labels.
serviceobject
The shipping service.
Child attributes
- uidstringnullable
  The service uid.
- namestringnullable
  The service name.
- umbrellaNamestringnullable
  The carrier or brand the service belongs to.
- serviceTypestringnullable
  ground, air or sea.
totalChargePricenumber
The quoted price. Includes insuranceFee whether or not the shipment is insured, and improvedFoamProtectionFee. Subtract insuranceFee when the shipment is not insured.
insuranceFeenumber
The price of insuring the shipment with this service. It is already inside totalChargePrice; it is charged only when the shipment is insured.
improvedFoamProtectionFeenumber
The price of improved foam protection, already inside totalChargePrice. 0 unless the shipment asks for it.
shipmentChargeTotalPricenumber
The price of the shipping service alone; coupon discounts are calculated on it. It is not what the label costs: see totalChargePrice.
pickupFeenumber
Added to the label price when the parcels are picked up.
minimumPickupFeenumber
Added to the label price when the parcels are picked up.

The Rate object

{
  "uid": "k3m9x2p7q1zt",
  "service": {
    "uid": "q8c2kd0x1m4z",
    "name": "USPS Priority Mail",
    "umbrellaName": "USPS",
    "serviceType": "ground"
  },
  "totalChargePrice": 20.75,
  "insuranceFee": 2.35,
  "improvedFoamProtectionFee": 0,
  "shipmentChargeTotalPrice": 18.4,
  "pickupFee": 0,
  "minimumPickupFee": 0
}

Calculate shipping rates

POST/shipments/rates

Requires an access token

Quotes every service available for a shipment. Send the shipment as you would create it; accountId is optional. To quote packages that are already in your locker, send each item’s uid from GET /forwarder as forwardingOrderItemId on a parcel item (the From locker items example).

Every rate’s totalChargePrice includes insurance (insuranceFee), even when you do not ask for it. If the shipment will not be insured (the default), subtract insuranceFee to get the price of its label.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

The shipment to create.

accountIdstringrequired
- string
  Your account uid, as returned by POST /authentication.
- string
  Your account number (CU…).
  at most 10 characters
totalValuenumberrequired
<= 2999
insuranceboolean
Insure the shipment. Defaults to false. Rates always include the insurance price (insuranceFee) in totalChargePrice; it is charged only when this is true.
incotermsstringrequired
Allowed values:DDUDDP
weightUnitstring
Unit of weight for every parcel that does not set its own weightUnit. With no unit on the parcel or here, weights are read as grams.
Allowed values:gmkgozlb
dimUnitstring
Unit of length, width and height for every parcel that does not set its own dimUnit. With no unit on the parcel or here, sizes are read as centimeters.
Allowed values:cmin
senderobjectrequired
Child attributes
- addressobjectrequired
  Child attributes
  cityobject
  Child attributes
  namestring
  stateobject
  Child attributes
  namestring
  streetstring
  Street address, including the building or apartment number.
  postalCodestring
- countryobjectrequired
  A country, by its ISO 3166-1 alpha-2 code.
  Child attributes
  isoCodestring
  Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
  exactly 2 characters
recipientobjectrequired
Child attributes
- addressobjectrequired
  Child attributes
  cityobject
  Child attributes
  namestring
  stateobject
  Child attributes
  namestring
  streetstring
  Street address, including the building or apartment number.
  postalCodestring
- countryobjectrequired
  A country, by its ISO 3166-1 alpha-2 code.
  Child attributes
  isoCodestring
  Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
  exactly 2 characters
parcelsarray of objectrequired
at least 1 items · at most 100 items
Child attributes
- dimUnitstringrequired
  Unit of length, width and height.
  Allowed values:cmin
- widthnumberrequired
- lengthnumberrequired
- heightnumberrequired
- weightUnitstringrequired
  Unit of weight.
  Allowed values:gmkgozlb
  Default: gm
- weightnumberrequired
  >= 0.01
- parcel_itemsarray of objectrequired
  at least 1 items · at most 100 items
  Child attributes
  skustring
  forwardingOrderItemIdstring
  Ships a package that is already in your locker: the uid of the forwarding order item, as listed by GET /forwarder. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown uid, or an item of another account, is a 400.
  descriptionstringrequired
  at least 1 characters
  categoryobjectrequired
  Child attributes
  slugstringrequired
  pricenumberrequired
  qtynumberrequired
  originCountryobject
  Child attributes
  isoCodestring
  at least 2 characters
  weightnumber
  currencystring | Currencyrequired
  Currency of the item value: an ISO 4217 code, or a currency object.
  Child attributes
  One of

Responses

201

The available rates. Each totalChargePrice includes insurance (insuranceFee); see the Rate object.

The Rate object

400

Invalid parcels, or an unknown forwardingOrderItemId

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

POST/shipments/rates

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments/rates' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "totalValue": 2999,
  "insurance": true,
  "incoterms": "DDU",
  "sender": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}'

Request examples

{
  "accountId": "CU1234567",
  "totalValue": 2999,
  "insurance": true,
  "incoterms": "DDU",
  "sender": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}

Response

[
  {
    "uid": "k3m9x2p7q1zt",
    "service": {
      "uid": "q8c2kd0x1m4z",
      "name": "USPS Priority Mail",
      "umbrellaName": "USPS",
      "serviceType": "ground"
    },
    "totalChargePrice": 20.75,
    "insuranceFee": 2.35,
    "improvedFoamProtectionFee": 0,
    "shipmentChargeTotalPrice": 18.4,
    "pickupFee": 0,
    "minimumPickupFee": 0
  }
]

Try itSend a real request to Test from this page. No code needed.

Find shipments

GET/shipments

Requires an access token

Lists the shipments of your accounts.

Query parameters

accountIdstring
Limit the results to one of your accounts or one of their sub-accounts: its uid, its account number (CU…) or its external account number. Without it, the accounts you belong to and their sub-accounts are all included.
$limitnumber
Maximum number of results (default 20).
Default: 20
>= 0 · <= 500
$skipnumber
Number of results to skip, for paging.
Default: 0
>= 0

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

A page of your shipments.

totalintegerrequired
Total number of matching records.
limitintegerrequired
Page size used for this response.
skipintegerrequired
Number of records skipped before this page.
dataarray of Shipmentrequired
The Shipment object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

GET/shipments

curl 'https://sandbox.weshipyou.com/api/v1/shipments' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "total": 1,
  "limit": 20,
  "skip": 0,
  "data": [
    {
      "uid": "wwbvygom0rlz",
      "state": "created",
      "statusTracking": "in transit",
      "transactionState": null,
      "externalReferenceCode": "shp1x6",
      "externalCustomerId": null,
      "externalUniqueId": null,
      "incoterms": "DDU",
      "weightUnit": "gm",
      "dimUnit": "cm",
      "weight": 1000,
      "length": 10,
      "width": 10,
      "height": 10,
      "totalValue": 10,
      "insurance": 0,
      "insuranceAmount": null,
      "appliedCouponDiscount": 0,
      "sellerNotes": null,
      "buyerNotes": null,
      "labelCreatedAt": null,
      "deliveredAt": null,
      "cancellationReason": null,
      "cancellationReasonCode": null,
      "customsAuthorizations": {
        "required": [],
        "mincomDocumentsCount": 0,
        "canCustomerEdit": true,
        "recipientAuthorization": "optional",
        "recipientAuthorizationDocumentsCount": 0,
        "canCustomerEditRecipientAuthorization": true
      },
      "createdAt": "2026-11-01T00:37:50.000Z",
      "updatedAt": "2026-11-01T00:37:50.000Z"
    }
  ]
}

Try itSend a real request to Test from this page. No code needed.

Add a new shipment to your account

POST/shipments

Requires an access token

Creates a shipment (no label yet). accountId accepts the account uid, its account number (CU…) or its external account number. Rate it with POST /shipments/rates and buy the label with POST /shipments/labels.

To ship packages that are already in your locker, list them with GET /forwarder and send each item’s uid as forwardingOrderItemId on a parcel item (the From locker items example).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

The shipment to create.

accountIdstring | integerrequired
- string | integer
  Your account uid, as returned by POST /authentication, or the uid of one of its sub-accounts (GET /accounts) to ship for that sub-account.
- string | integer
  Your account number (CU…).
  at most 10 characters
senderobjectrequired
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
recipientobjectrequired
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
totalValuenumberrequired
<= 2999
externalReferenceCodestring
externalCustomerIdstringnullable
insuranceboolean | integer
Insure the shipment. Defaults to false. Rates always include the insurance price (insuranceFee) in totalChargePrice; it is charged only when this is true.
incotermsstringrequired
Allowed values:DDUDDP
weightUnitstring
Unit of weight for every parcel that does not set its own weightUnit. Saved on the shipment, and the dashboard shows the shipment’s weight in it. Defaults to the first parcel’s weightUnit.
Allowed values:gmkgozlb
dimUnitstring
Unit of length, width and height for every parcel that does not set its own dimUnit. Saved on the shipment. Defaults to the first parcel’s dimUnit.
Allowed values:cmin
parcelsarray of objectrequired
at least 1 items · at most 100 items
Child attributes
- dimUnitstringrequired
  Unit of length, width and height.
  Allowed values:cmin
- widthnumberrequired
- lengthnumberrequired
- heightnumberrequired
- weightUnitstringrequired
  Unit of weight.
  Allowed values:gmkgozlb
  Default: gm
- weightnumberrequired
  >= 0.01
- parcel_itemsarray of objectrequired
  at least 1 items · at most 100 items
  Child attributes
  skustring
  forwardingOrderItemIdstring
  Ships a package that is already in your locker: the uid of the forwarding order item, as listed by GET /forwarder. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown uid, or an item of another account, is a 400.
  descriptionstringrequired
  at least 1 characters
  categoryobjectrequired
  Child attributes
  slugstringrequired
  pricenumberrequired
  qtynumberrequired
  originCountryobject
  Child attributes
  isoCodestring
  at least 2 characters
  weightnumber
  currencystring | Currencyrequired
  Currency of the item value: an ISO 4217 code, or a currency object.
  Child attributes
  One of

Responses

201

The created shipment

The Shipment object

400

Validation error; data holds the message for each invalid field

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

POST/shipments

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "sender": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "totalValue": 2999,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "insurance": true,
  "incoterms": "DDU",
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}'

Request examples

{
  "accountId": "CU1234567",
  "sender": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "totalValue": 2999,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "insurance": true,
  "incoterms": "DDU",
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}

Response

{
  "uid": "42ailx0umn2q",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 2.5,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 450,
  "insurance": true,
  "insuranceAmount": null,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "sender": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "recipient": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "createdAt": "2026-11-01T00:37:51.000Z",
  "updatedAt": "2026-11-01T00:37:51.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Get a shipment

GET/shipments/{shipmentId}

Requires an access token

Returns one of your shipments.

Path parameters

shipmentIdstringrequired
The shipment uid, or its WeShipYou tracking number (WSY…).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

The shipment

The Shipment object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

404

No shipment has that id

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

GET/shipments/{shipmentId}

curl 'https://sandbox.weshipyou.com/api/v1/shipments/{shipmentId}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "uid": "wwbvygom0rlz",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "shp1x6",
  "externalCustomerId": null,
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 1000,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 10,
  "insurance": 0,
  "insuranceAmount": null,
  "appliedCouponDiscount": 0,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "customsAuthorizations": {
    "required": [],
    "mincomDocumentsCount": 0,
    "canCustomerEdit": true,
    "recipientAuthorization": "optional",
    "recipientAuthorizationDocumentsCount": 0,
    "canCustomerEditRecipientAuthorization": true
  },
  "createdAt": "2026-11-01T00:37:50.000Z",
  "updatedAt": "2026-11-01T00:37:50.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Update a shipment

PATCH/shipments/{shipmentId}

Requires an access token

Changes the fields you send and keeps every other field as it is. To change an address, send the whole sender or recipient object (or { "id": <address id>, "useExistingAddress": true } to use one from your address book); to change the contents, send the whole parcels array. Rates are recalculated after the change. A delivered shipment cannot be edited.

Path parameters

shipmentIdstringrequired
The shipment uid, or its WeShipYou tracking number (WSY…).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

Any of the shipment fields.

accountIdstring
- string
  Your account uid, as returned by POST /authentication.
- string
  Your account number (CU…).
  at most 10 characters
senderobject
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
recipientobject
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
totalValuenumber
<= 2999
externalReferenceCodestring
externalCustomerIdstring
insuranceboolean
Insure the shipment. Defaults to false. Rates always include the insurance price (insuranceFee) in totalChargePrice; it is charged only when this is true.
incotermsstring
Allowed values:DDUDDP
parcelsarray of object
at least 1 items · at most 100 items
Child attributes
- dimUnitstringrequired
  Unit of length, width and height.
  Allowed values:cmin
- widthnumberrequired
- lengthnumberrequired
- heightnumberrequired
- weightUnitstringrequired
  Unit of weight.
  Allowed values:gmkgozlb
  Default: gm
- weightnumberrequired
  >= 0.01
- parcel_itemsarray of objectrequired
  at least 1 items · at most 100 items
  Child attributes
  skustring
  forwardingOrderItemIdstring
  Ships a package that is already in your locker: the uid of the forwarding order item, as listed by GET /forwarder. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown uid, or an item of another account, is a 400.
  descriptionstringrequired
  at least 1 characters
  categoryobjectrequired
  Child attributes
  slugstringrequired
  pricenumberrequired
  qtynumberrequired
  originCountryobject
  Child attributes
  isoCodestring
  at least 2 characters
  weightnumber
  currencystring | Currencyrequired
  Currency of the item value: an ISO 4217 code, or a currency object.
  Child attributes
  One of

Responses

200

The updated shipment

The Shipment object

400

Validation error, or the shipment can no longer be edited

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

404

No shipment has that id

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

PATCH/shipments/{shipmentId}

curl -X PATCH 'https://sandbox.weshipyou.com/api/v1/shipments/{shipmentId}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "sender": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "totalValue": 2999,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "insurance": true,
  "incoterms": "DDU",
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}'

Response

{
  "uid": "42ailx0umn2q",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "ORDER-1002",
  "externalCustomerId": "CUST-42",
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 2.5,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 450,
  "insurance": true,
  "insuranceAmount": null,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "sender": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "recipient": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "createdAt": "2026-11-01T00:37:51.000Z",
  "updatedAt": "2026-11-01T00:37:52.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Delete a shipment

DELETE/shipments/{shipmentId}

Requires an access token

Deletes a shipment that has no label yet (state created). To cancel a shipment whose label is already bought, use DELETE /shipments/labels/{trackingNumber}.

Path parameters

shipmentIdstringrequired
The shipment uid, or its WeShipYou tracking number (WSY…).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

The deleted shipment

The Shipment object

400

The shipment cannot be deleted in its current state

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

404

No shipment has that id

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

DELETE/shipments/{shipmentId}

curl -X DELETE 'https://sandbox.weshipyou.com/api/v1/shipments/{shipmentId}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "uid": "wwbvygom0rlz",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "shp1x6",
  "externalCustomerId": null,
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 1000,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 10,
  "insurance": 0,
  "insuranceAmount": null,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "createdAt": "2026-11-01T00:37:50.000Z",
  "updatedAt": "2026-11-01T00:37:50.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Get shipment categories

GET/shipments/categories

Requires an access token

Lists the content categories a parcel item can declare.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

A page of shipment content categories.

totalintegerrequired
Total number of matching records.
limitintegerrequired
Page size used for this response.
skipintegerrequired
Number of records skipped before this page.
dataarray of Categoryrequired
The Category object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

Forbidden

GET/shipments/categories

curl 'https://sandbox.weshipyou.com/api/v1/shipments/categories' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "total": 30,
  "limit": 500,
  "skip": 0,
  "data": [
    {
      "uid": "u40h56jccmdi",
      "name": "Phone Accessory (no battery)",
      "slug": "accessory_no_battery",
      "weight": null,
      "length": null,
      "width": null,
      "height": null,
      "containsDocuments": 0,
      "containsOtherDg": 0,
      "containsLiquids": 0,
      "containsBatteryPi967": 0,
      "containsBatteryPi966": 0,
      "containsBatteryPi965": 0,
      "parentId": null
    }
  ]
}

Try itSend a real request to Test from this page. No code needed.

Get country categories

GET/shipments/country-categories

Requires an access token

Lists the content categories a destination country uses for customs.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

A page of country-specific content categories.

totalintegerrequired
Total number of matching records.
limitintegerrequired
Page size used for this response.
skipintegerrequired
Number of records skipped before this page.
dataarray of Country categoryrequired
The Country category object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

Forbidden

GET/shipments/country-categories

curl 'https://sandbox.weshipyou.com/api/v1/shipments/country-categories' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "total": 0,
  "limit": 500,
  "skip": 0,
  "data": []
}

Try itSend a real request to Test from this page. No code needed.

Buy labels

POST/shipments/labels

Requires an access token

Buys the label of one or more shipments at the rate you chose. The charge is booked in your WeShipYou wallet: your balance is used first and only the remainder is charged to paymentMethod.

Each label costs its rate’s totalChargePrice minus insuranceFee when the shipment is not insured (rates always include insurance), plus pickupFee and minimumPickupFee for a pickup handover. A coupon lowers it further.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

accountIdstring
Account uid, account number (CU…) or external account number.
paymentMethod"credit_line" | object
How to pay what your wallet balance does not cover: "credit_line" for accounts with a credit line, or a saved card as { "paymentMethodId": "pm_…" }. Can be omitted when the balance covers the whole amount.
Child attributes
One of
Allowed values:credit_line
paymentMethodIdstring
usePointsboolean
Spend your WeShipYou points first.
insuranceboolean
Insure every shipment of this purchase (true) or none of them (false). Leave it out to keep each shipment’s own insurance.
handoverOptionsarray of objectrequired
Child attributes
- handoverOptionstringrequired
  Allowed values:dropoffpickup
- pickupDatestring <date>
- pickupTimestring
- shipmentsarray of objectrequired
  Child attributes
  shipmentIdstringrequired
  Shipment uid or WeShipYou tracking number.
  rateIdstringrequired
  The uid of the chosen rate of that shipment.

Responses

201

The outcome of each label batch

statusstringrequired
Outcome of the batch.
Allowed values:fulfilledrejected
reasonany
Why the batch failed, when status is rejected.

400

Invalid request, payment not found or insufficient funds

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

POST/shipments/labels

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments/labels' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "paymentMethod": "credit_line",
  "usePoints": true,
  "insurance": false,
  "handoverOptions": [
    {
      "handoverOption": "dropoff",
      "pickupDate": "2026-10-02",
      "pickupTime": "10:00",
      "shipments": [
        {
          "shipmentId": "6f1c2b8e-3d4a-4f5b-9c6d-7e8f9a0b1c2d",
          "rateId": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e"
        }
      ]
    }
  ]
}'

Response

[
  {
    "status": "fulfilled"
  }
]

Try itSend a real request to Test from this page. No code needed.

Cancel a label

DELETE/shipments/labels/{trackingNumber}

Requires an access token

Cancels a label the carrier has not picked up yet. What you paid for it is credited back to your WeShipYou wallet.

Path parameters

trackingNumberstringrequired
The WeShipYou tracking number of the label.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

The label was cancelled

idstringrequired
WeShipYou tracking number of the cancelled label.

400

The label can no longer be cancelled

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

404

Not found

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

409

The shipment changed state while cancelling; retry

namestring
Always Conflict
messagestring
codenumber
Always 409
classNamestring
Always conflict
dataobject

DELETE/shipments/labels/{trackingNumber}

curl -X DELETE 'https://sandbox.weshipyou.com/api/v1/shipments/labels/{trackingNumber}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "id": "WSYOP5B60J3SCU"
}

Try itSend a real request to Test from this page. No code needed.

Confirm a delivery

POST/shipments/confirm-delivery

No access token needed

Records that the recipient received a shipment that is in transit or delivered. No access token is needed: the tracking number and the account number identify the shipment.

A shipment that is already delivered can always be confirmed. An in_transit shipment can be confirmed only when it is overdue (its label was bought at least 30 days ago and, when it has a delivery promise, at least 15 days have passed since that date) and it has not reached WeShipYou at destination. Once the package is with WeShipYou in Cuba (picked up at the airport or port, on a transit trip or a delivery route), only WeShipYou marks it delivered. A refusal is a 400 with data.code: delivery-confirmation-at-destination, or delivery-confirmation-too-early with data.availableFrom.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

trackingNumberstringrequired
accountNumberstringrequired
The account number of the shipment owner (CU…).

Responses

201

Delivery recorded

okboolean
Always true
idstring
The tracking number.

400

Missing fields, unknown account or shipment, or a shipment that is not in transit

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

POST/shipments/confirm-delivery

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments/confirm-delivery' \
  -H "Content-Type: application/json" \
  -d '{
  "trackingNumber": "WSY0000000000US",
  "accountNumber": "CU1234567"
}'

Response

{
  "ok": true,
  "id": "WSYZD8KI41VSCU"
}

Try itSend a real request to Test from this page. No code needed.

Shipments

Create, rate, label, cancel and confirm your shipments

POST/shipments/rates
GET/shipments
POST/shipments
GET/shipments/{shipmentId}
PATCH/shipments/{shipmentId}
DELETE/shipments/{shipmentId}
GET/shipments/categories
GET/shipments/country-categories
POST/shipments/labels
DELETE/shipments/labels/{trackingNumber}
POST/shipments/confirm-delivery

The Shipment object

A shipment: what is sent, from whom, to whom, and its label and delivery status.

Attributes

uidstringrequired
Shipment UID. Use it as shipmentId.
statestringrequired
Lifecycle state, from created through label_created to delivered or cancelled.
statusTrackingstringnullable
Latest carrier tracking status, in words.
transactionStatestringnullable
Billing state of the shipment, when it was charged or refunded.
externalReferenceCodestringnullable
Your own reference for the shipment.
externalCustomerIdstringnullable
Your own customer reference.
externalUniqueIdstringnullable
Your own idempotency reference.
incotermsstringrequired
Who pays duties: the recipient (DDU) or the sender (DDP).
Allowed values:DDUDDP
weightUnitstringrequired
Unit of weight.
Allowed values:gmkgozlb
dimUnitstringrequired
Unit of length, width and height.
weightnumbernullable
Total weight.
lengthnumbernullable
Length of the box.
widthnumbernullable
Width of the box.
heightnumbernullable
Height of the box.
totalValuenumbernullable
Declared value of the contents, USD.
insuranceboolean | integer
The shipment is insured. 1/true or 0/false.
insuranceAmountnumbernullable
Insured amount, USD.
appliedCouponDiscountnumbernullable
Coupon discount applied to the label price, USD.
sellerNotesstringnullable
Notes from the sender.
buyerNotesstringnullable
Notes from the recipient.
labelCreatedAtstring <date-time>nullable
When the label was bought.
deliveredAtstring <date-time>nullable
When the carrier delivered the shipment.
cancellationReasonstringnullable
Why the shipment was cancelled.
cancellationReasonCodestringnullable
Machine code of the cancellation reason.
customsAuthorizationsobject
Customs documents the destination requires, and whether the customer can still edit them.
senderobjectnullable
The sender. Included when the shipment is read on its own.
Child attributes
- uidstring
  Address book entry UID.
- nicknamestringnullable
  Your label for the entry.
- companyNamestringnullable
  Company name.
- namestringnullable
  Full name.
- taxIdstringnullable
  Tax ID.
- emailstringnullable
  Email address.
- phonestringnullable
  Phone number.
- isResidentialboolean | integer
  Residential delivery address.
- statusstring
  Entry status.
- addressobjectnullable
  A postal address as WeShipYou parsed it.
  Child attributes
  uidstring
  Address UID.
  houseNumberstringnullable
  House or building number.
  roadstringnullable
  Street name.
  unitstringnullable
  Apartment, suite or unit.
  cityobjectnullable
  Child attributes
  namestring
  City name.
  stateobjectnullable
  Child attributes
  namestring
  isoCodestringnullable
  State code.
  countryobjectnullable
  Child attributes
  isoCodestring
  namestring
  postal_codeobjectnullable
  Child attributes
  postalCodestring
recipientobjectnullable
The recipient. Included when the shipment is read on its own.
Child attributes
- uidstring
  Address book entry UID.
- nicknamestringnullable
  Your label for the entry.
- companyNamestringnullable
  Company name.
- namestringnullable
  Full name.
- taxIdstringnullable
  Tax ID.
- emailstringnullable
  Email address.
- phonestringnullable
  Phone number.
- isResidentialboolean | integer
  Residential delivery address.
- statusstring
  Entry status.
- addressobjectnullable
  A postal address as WeShipYou parsed it.
  Child attributes
  uidstring
  Address UID.
  houseNumberstringnullable
  House or building number.
  roadstringnullable
  Street name.
  unitstringnullable
  Apartment, suite or unit.
  cityobjectnullable
  Child attributes
  namestring
  City name.
  stateobjectnullable
  Child attributes
  namestring
  isoCodestringnullable
  State code.
  countryobjectnullable
  Child attributes
  isoCodestring
  namestring
  postal_codeobjectnullable
  Child attributes
  postalCodestring
parcelsarray of object
The parcels and their items. Included when the shipment is read on its own.
parcel_ratesarray of Rate
The services this shipment can be sent with and their prices. Included in the answer of POST /shipments and PATCH /shipments/{shipmentId}; pick one and buy it with POST /shipments/labels. Their totalChargePrice includes insurance (insuranceFee) even when the shipment is not insured; see the Rate object.
Child attributes
- uidstringrequired
  The rate id. Send it as rateId to POST /shipments/labels.
- serviceobject
  The shipping service.
  Child attributes
  uidstringnullable
  The service uid.
  namestringnullable
  The service name.
  umbrellaNamestringnullable
  The carrier or brand the service belongs to.
  serviceTypestringnullable
  ground, air or sea.
- totalChargePricenumber
  The quoted price. Includes insuranceFee whether or not the shipment is insured, and improvedFoamProtectionFee. Subtract insuranceFee when the shipment is not insured.
- insuranceFeenumber
  The price of insuring the shipment with this service. It is already inside totalChargePrice; it is charged only when the shipment is insured.
- improvedFoamProtectionFeenumber
  The price of improved foam protection, already inside totalChargePrice. 0 unless the shipment asks for it.
- shipmentChargeTotalPricenumber
  The price of the shipping service alone; coupon discounts are calculated on it. It is not what the label costs: see totalChargePrice.
- pickupFeenumber
  Added to the label price when the parcels are picked up.
- minimumPickupFeenumber
  Added to the label price when the parcels are picked up.
labelobjectnullable
The label, once it is bought. Included when the shipment is read on its own (GET /shipments/{shipmentId}).
Child attributes
- trackingNumberstringnullable
  The WeShipYou tracking number (WSY…). Use it with GET /tracking/{trackingNumber} and to cancel the label.
createdAtstring <date-time>required
When the shipment was created.
updatedAtstring <date-time>required
When the shipment last changed.

The Shipment object

{
  "uid": "wwbvygom0rlz",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "shp1x6",
  "externalCustomerId": null,
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 1000,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 10,
  "insurance": 0,
  "insuranceAmount": null,
  "appliedCouponDiscount": 0,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "customsAuthorizations": {
    "required": [],
    "mincomDocumentsCount": 0,
    "canCustomerEdit": true,
    "recipientAuthorization": "optional",
    "recipientAuthorizationDocumentsCount": 0,
    "canCustomerEditRecipientAuthorization": true
  },
  "createdAt": "2026-11-01T00:37:50.000Z",
  "updatedAt": "2026-11-01T00:37:50.000Z"
}

The Category object

A shipment content category. Each parcel item declares one.

Attributes

uidstringrequired
Category UID.
namestringrequired
Display name.
slugstringrequired
Stable machine name.
weightnumbernullable
Default weight for one unit, in grams.
lengthnumbernullable
Default length, in centimeters.
widthnumbernullable
Default width, in centimeters.
heightnumbernullable
Default height, in centimeters.
containsDocumentsboolean | integer
Items in this category are documents. 1/true or 0/false.
containsOtherDgboolean | integer
Items in this category are dangerous goods other than batteries. 1/true or 0/false.
containsLiquidsboolean | integer
Items in this category contain liquids. 1/true or 0/false.
containsBatteryPi967boolean | integer
Lithium-ion batteries contained in equipment (PI 967). 1/true or 0/false.
containsBatteryPi966boolean | integer
Lithium-ion batteries packed with equipment (PI 966). 1/true or 0/false.
containsBatteryPi965boolean | integer
Lithium-ion batteries on their own (PI 965). 1/true or 0/false.
parentIdintegernullable
Parent category, when this is a sub-category.

The Category object

{
  "uid": "u40h56jccmdi",
  "name": "Phone Accessory (no battery)",
  "slug": "accessory_no_battery",
  "weight": null,
  "length": null,
  "width": null,
  "height": null,
  "containsDocuments": 0,
  "containsOtherDg": 0,
  "containsLiquids": 0,
  "containsBatteryPi967": 0,
  "containsBatteryPi966": 0,
  "containsBatteryPi965": 0,
  "parentId": null
}

The Country category object

Attributes

uidstringnullable
namestringnullable
slugstringnullable
weightnumbernullable
lengthnumbernullable
widthnumbernullable
heightnumbernullable
containsDocumentsbooleannullable
containsOtherDgbooleannullable
containsLiquidsbooleannullable
containsBatteryPi967booleannullable
containsBatteryPi966booleannullable
containsBatteryPi965booleannullable
customsValuenumbernullable
qtynumbernullable
maxWeightnumbernullable
unitTypestringnullable
observationsstringnullable
isDiscontinuedbooleannullable
createdAtstring <date-time>nullable
updatedAtstring <date-time>nullable
parentIdnumbernullable

The Rate object

A service the shipment can be sent with, and its price in USD.

label price = totalChargePrice − insuranceFee when the shipment is not insured, or totalChargePrice when it is;
plus pickupFee and minimumPickupFee when the parcels are picked up (handoverOption: "pickup" in POST /shipments/labels).

A coupon lowers that price further.

Attributes

uidstring
The rate id. Send it as rateId to POST /shipments/labels.
serviceobject
The shipping service.
Child attributes
- uidstringnullable
  The service uid.
- namestringnullable
  The service name.
- umbrellaNamestringnullable
  The carrier or brand the service belongs to.
- serviceTypestringnullable
  ground, air or sea.
totalChargePricenumber
The quoted price. Includes insuranceFee whether or not the shipment is insured, and improvedFoamProtectionFee. Subtract insuranceFee when the shipment is not insured.
insuranceFeenumber
The price of insuring the shipment with this service. It is already inside totalChargePrice; it is charged only when the shipment is insured.
improvedFoamProtectionFeenumber
The price of improved foam protection, already inside totalChargePrice. 0 unless the shipment asks for it.
shipmentChargeTotalPricenumber
The price of the shipping service alone; coupon discounts are calculated on it. It is not what the label costs: see totalChargePrice.
pickupFeenumber
Added to the label price when the parcels are picked up.
minimumPickupFeenumber
Added to the label price when the parcels are picked up.

The Rate object

{
  "uid": "k3m9x2p7q1zt",
  "service": {
    "uid": "q8c2kd0x1m4z",
    "name": "USPS Priority Mail",
    "umbrellaName": "USPS",
    "serviceType": "ground"
  },
  "totalChargePrice": 20.75,
  "insuranceFee": 2.35,
  "improvedFoamProtectionFee": 0,
  "shipmentChargeTotalPrice": 18.4,
  "pickupFee": 0,
  "minimumPickupFee": 0
}

Calculate shipping rates

POST/shipments/rates

Requires an access token

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

The shipment to create.

accountIdstringrequired
- string
  Your account uid, as returned by POST /authentication.
- string
  Your account number (CU…).
  at most 10 characters
totalValuenumberrequired
<= 2999
insuranceboolean
Insure the shipment. Defaults to false. Rates always include the insurance price (insuranceFee) in totalChargePrice; it is charged only when this is true.
incotermsstringrequired
Allowed values:DDUDDP
weightUnitstring
Unit of weight for every parcel that does not set its own weightUnit. With no unit on the parcel or here, weights are read as grams.
Allowed values:gmkgozlb
dimUnitstring
Unit of length, width and height for every parcel that does not set its own dimUnit. With no unit on the parcel or here, sizes are read as centimeters.
Allowed values:cmin
senderobjectrequired
Child attributes
- addressobjectrequired
  Child attributes
  cityobject
  Child attributes
  namestring
  stateobject
  Child attributes
  namestring
  streetstring
  Street address, including the building or apartment number.
  postalCodestring
- countryobjectrequired
  A country, by its ISO 3166-1 alpha-2 code.
  Child attributes
  isoCodestring
  Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
  exactly 2 characters
recipientobjectrequired
Child attributes
- addressobjectrequired
  Child attributes
  cityobject
  Child attributes
  namestring
  stateobject
  Child attributes
  namestring
  streetstring
  Street address, including the building or apartment number.
  postalCodestring
- countryobjectrequired
  A country, by its ISO 3166-1 alpha-2 code.
  Child attributes
  isoCodestring
  Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
  exactly 2 characters
parcelsarray of objectrequired
at least 1 items · at most 100 items
Child attributes
- dimUnitstringrequired
  Unit of length, width and height.
  Allowed values:cmin
- widthnumberrequired
- lengthnumberrequired
- heightnumberrequired
- weightUnitstringrequired
  Unit of weight.
  Allowed values:gmkgozlb
  Default: gm
- weightnumberrequired
  >= 0.01
- parcel_itemsarray of objectrequired
  at least 1 items · at most 100 items
  Child attributes
  skustring
  forwardingOrderItemIdstring
  Ships a package that is already in your locker: the uid of the forwarding order item, as listed by GET /forwarder. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown uid, or an item of another account, is a 400.
  descriptionstringrequired
  at least 1 characters
  categoryobjectrequired
  Child attributes
  slugstringrequired
  pricenumberrequired
  qtynumberrequired
  originCountryobject
  Child attributes
  isoCodestring
  at least 2 characters
  weightnumber
  currencystring | Currencyrequired
  Currency of the item value: an ISO 4217 code, or a currency object.
  Child attributes
  One of

Responses

201

The available rates. Each totalChargePrice includes insurance (insuranceFee); see the Rate object.

The Rate object

400

Invalid parcels, or an unknown forwardingOrderItemId

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

POST/shipments/rates

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments/rates' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "totalValue": 2999,
  "insurance": true,
  "incoterms": "DDU",
  "sender": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}'

Request examples

{
  "accountId": "CU1234567",
  "totalValue": 2999,
  "insurance": true,
  "incoterms": "DDU",
  "sender": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "country": {
      "isoCode": "US"
    }
  },
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}

Response

[
  {
    "uid": "k3m9x2p7q1zt",
    "service": {
      "uid": "q8c2kd0x1m4z",
      "name": "USPS Priority Mail",
      "umbrellaName": "USPS",
      "serviceType": "ground"
    },
    "totalChargePrice": 20.75,
    "insuranceFee": 2.35,
    "improvedFoamProtectionFee": 0,
    "shipmentChargeTotalPrice": 18.4,
    "pickupFee": 0,
    "minimumPickupFee": 0
  }
]

Try itSend a real request to Test from this page. No code needed.

Find shipments

GET/shipments

Requires an access token

Lists the shipments of your accounts.

Query parameters

accountIdstring
Limit the results to one of your accounts or one of their sub-accounts: its uid, its account number (CU…) or its external account number. Without it, the accounts you belong to and their sub-accounts are all included.
$limitnumber
Maximum number of results (default 20).
Default: 20
>= 0 · <= 500
$skipnumber
Number of results to skip, for paging.
Default: 0
>= 0

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

A page of your shipments.

totalintegerrequired
Total number of matching records.
limitintegerrequired
Page size used for this response.
skipintegerrequired
Number of records skipped before this page.
dataarray of Shipmentrequired
The Shipment object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

GET/shipments

curl 'https://sandbox.weshipyou.com/api/v1/shipments' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "total": 1,
  "limit": 20,
  "skip": 0,
  "data": [
    {
      "uid": "wwbvygom0rlz",
      "state": "created",
      "statusTracking": "in transit",
      "transactionState": null,
      "externalReferenceCode": "shp1x6",
      "externalCustomerId": null,
      "externalUniqueId": null,
      "incoterms": "DDU",
      "weightUnit": "gm",
      "dimUnit": "cm",
      "weight": 1000,
      "length": 10,
      "width": 10,
      "height": 10,
      "totalValue": 10,
      "insurance": 0,
      "insuranceAmount": null,
      "appliedCouponDiscount": 0,
      "sellerNotes": null,
      "buyerNotes": null,
      "labelCreatedAt": null,
      "deliveredAt": null,
      "cancellationReason": null,
      "cancellationReasonCode": null,
      "customsAuthorizations": {
        "required": [],
        "mincomDocumentsCount": 0,
        "canCustomerEdit": true,
        "recipientAuthorization": "optional",
        "recipientAuthorizationDocumentsCount": 0,
        "canCustomerEditRecipientAuthorization": true
      },
      "createdAt": "2026-11-01T00:37:50.000Z",
      "updatedAt": "2026-11-01T00:37:50.000Z"
    }
  ]
}

Try itSend a real request to Test from this page. No code needed.

Add a new shipment to your account

POST/shipments

Requires an access token

To ship packages that are already in your locker, list them with GET /forwarder and send each item’s uid as forwardingOrderItemId on a parcel item (the From locker items example).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

The shipment to create.

accountIdstring | integerrequired
- string | integer
  Your account uid, as returned by POST /authentication, or the uid of one of its sub-accounts (GET /accounts) to ship for that sub-account.
- string | integer
  Your account number (CU…).
  at most 10 characters
senderobjectrequired
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
recipientobjectrequired
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
totalValuenumberrequired
<= 2999
externalReferenceCodestring
externalCustomerIdstringnullable
insuranceboolean | integer
Insure the shipment. Defaults to false. Rates always include the insurance price (insuranceFee) in totalChargePrice; it is charged only when this is true.
incotermsstringrequired
Allowed values:DDUDDP
weightUnitstring
Unit of weight for every parcel that does not set its own weightUnit. Saved on the shipment, and the dashboard shows the shipment’s weight in it. Defaults to the first parcel’s weightUnit.
Allowed values:gmkgozlb
dimUnitstring
Unit of length, width and height for every parcel that does not set its own dimUnit. Saved on the shipment. Defaults to the first parcel’s dimUnit.
Allowed values:cmin
parcelsarray of objectrequired
at least 1 items · at most 100 items
Child attributes
- dimUnitstringrequired
  Unit of length, width and height.
  Allowed values:cmin
- widthnumberrequired
- lengthnumberrequired
- heightnumberrequired
- weightUnitstringrequired
  Unit of weight.
  Allowed values:gmkgozlb
  Default: gm
- weightnumberrequired
  >= 0.01
- parcel_itemsarray of objectrequired
  at least 1 items · at most 100 items
  Child attributes
  skustring
  forwardingOrderItemIdstring
  Ships a package that is already in your locker: the uid of the forwarding order item, as listed by GET /forwarder. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown uid, or an item of another account, is a 400.
  descriptionstringrequired
  at least 1 characters
  categoryobjectrequired
  Child attributes
  slugstringrequired
  pricenumberrequired
  qtynumberrequired
  originCountryobject
  Child attributes
  isoCodestring
  at least 2 characters
  weightnumber
  currencystring | Currencyrequired
  Currency of the item value: an ISO 4217 code, or a currency object.
  Child attributes
  One of

Responses

201

The created shipment

The Shipment object

400

Validation error; data holds the message for each invalid field

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

POST/shipments

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "sender": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "totalValue": 2999,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "insurance": true,
  "incoterms": "DDU",
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}'

Request examples

{
  "accountId": "CU1234567",
  "sender": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "totalValue": 2999,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "insurance": true,
  "incoterms": "DDU",
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}

Response

{
  "uid": "42ailx0umn2q",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 2.5,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 450,
  "insurance": true,
  "insuranceAmount": null,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "sender": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "recipient": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "createdAt": "2026-11-01T00:37:51.000Z",
  "updatedAt": "2026-11-01T00:37:51.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Get a shipment

GET/shipments/{shipmentId}

Requires an access token

Returns one of your shipments.

Path parameters

shipmentIdstringrequired
The shipment uid, or its WeShipYou tracking number (WSY…).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

The shipment

The Shipment object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

404

No shipment has that id

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

GET/shipments/{shipmentId}

curl 'https://sandbox.weshipyou.com/api/v1/shipments/{shipmentId}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "uid": "wwbvygom0rlz",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "shp1x6",
  "externalCustomerId": null,
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 1000,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 10,
  "insurance": 0,
  "insuranceAmount": null,
  "appliedCouponDiscount": 0,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "customsAuthorizations": {
    "required": [],
    "mincomDocumentsCount": 0,
    "canCustomerEdit": true,
    "recipientAuthorization": "optional",
    "recipientAuthorizationDocumentsCount": 0,
    "canCustomerEditRecipientAuthorization": true
  },
  "createdAt": "2026-11-01T00:37:50.000Z",
  "updatedAt": "2026-11-01T00:37:50.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Update a shipment

PATCH/shipments/{shipmentId}

Requires an access token

Path parameters

shipmentIdstringrequired
The shipment uid, or its WeShipYou tracking number (WSY…).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

Any of the shipment fields.

accountIdstring
- string
  Your account uid, as returned by POST /authentication.
- string
  Your account number (CU…).
  at most 10 characters
senderobject
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
recipientobject
Child attributes
- useExistingAddressbooleanrequired
One of
useExistingAddressboolean
Always false
nicknamestringnullable
addressobjectrequired
Child attributes
cityobject
Child attributes
namestringnullable
stateobject
Child attributes
namestringnullable
streetstring
Street address, including the building or apartment number.
postalCodestring
namestringrequirednullable
at least 1 characters
companyNamestringnullable
taxIdstringnullable
taxIdCountryobject
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
phonestring <phone>requirednullable
at least 1 characters
emailstring <email>requirednullable
Recipient email address
countryobjectrequired
A country, by its ISO 3166-1 alpha-2 code.
Child attributes
isoCodestring
Allowed values:ADAEAFALAGAIAQAMAOARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCRCUCVCWCXCYCZDEDJDKDMDODZECEEEGEHERESETFIFJFKFMFOFRGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRXKKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMHUMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSSSESGSHSISJSKSLSMSNSOSRSTSVSXSYSZTCTDTFTGTHTJTKTLTMTNTOTRTTTVTWTZUAUGUMUSUYUZVAVCVEVGVIVNVUWFWSYTYEZAZMZWCSAN
exactly 2 characters
useExistingAddressboolean
addressobjectrequired
Child attributes
idnumber <int64>
Address ID
totalValuenumber
<= 2999
externalReferenceCodestring
externalCustomerIdstring
insuranceboolean
Insure the shipment. Defaults to false. Rates always include the insurance price (insuranceFee) in totalChargePrice; it is charged only when this is true.
incotermsstring
Allowed values:DDUDDP
parcelsarray of object
at least 1 items · at most 100 items
Child attributes
- dimUnitstringrequired
  Unit of length, width and height.
  Allowed values:cmin
- widthnumberrequired
- lengthnumberrequired
- heightnumberrequired
- weightUnitstringrequired
  Unit of weight.
  Allowed values:gmkgozlb
  Default: gm
- weightnumberrequired
  >= 0.01
- parcel_itemsarray of objectrequired
  at least 1 items · at most 100 items
  Child attributes
  skustring
  forwardingOrderItemIdstring
  Ships a package that is already in your locker: the uid of the forwarding order item, as listed by GET /forwarder. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown uid, or an item of another account, is a 400.
  descriptionstringrequired
  at least 1 characters
  categoryobjectrequired
  Child attributes
  slugstringrequired
  pricenumberrequired
  qtynumberrequired
  originCountryobject
  Child attributes
  isoCodestring
  at least 2 characters
  weightnumber
  currencystring | Currencyrequired
  Currency of the item value: an ISO 4217 code, or a currency object.
  Child attributes
  One of

Responses

200

The updated shipment

The Shipment object

400

Validation error, or the shipment can no longer be edited

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

404

No shipment has that id

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

PATCH/shipments/{shipmentId}

curl -X PATCH 'https://sandbox.weshipyou.com/api/v1/shipments/{shipmentId}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "sender": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "recipient": {
    "useExistingAddress": false,
    "nickname": "Main office",
    "address": {
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida"
        }
      },
      "street": "924 NW 36 Ave",
      "postalCode": "33033"
    },
    "name": "John Doe",
    "companyName": "We Ship You Corp",
    "taxId": "88-1345985",
    "taxIdCountry": {
      "isoCode": "US"
    },
    "phone": "+1 (786) 651-0451",
    "email": "john.doe@weshipyou.com",
    "country": {
      "isoCode": "US"
    }
  },
  "totalValue": 2999,
  "externalReferenceCode": "ORDER-1001",
  "externalCustomerId": "CUST-42",
  "insurance": true,
  "incoterms": "DDU",
  "parcels": [
    {
      "dimUnit": "cm",
      "width": 10,
      "length": 10,
      "height": 10,
      "weightUnit": "gm",
      "weight": 100,
      "parcel_items": [
        {
          "sku": "SKU-WSY-EXAMPLE",
          "description": "Play Station 4",
          "category": {
            "slug": "board_games"
          },
          "price": 450,
          "qty": 1,
          "originCountry": {
            "isoCode": "JP"
          },
          "weight": 2.5,
          "currency": "USD"
        }
      ]
    }
  ]
}'

Response

{
  "uid": "42ailx0umn2q",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "ORDER-1002",
  "externalCustomerId": "CUST-42",
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 2.5,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 450,
  "insurance": true,
  "insuranceAmount": null,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "sender": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "recipient": {
    "uid": "vbnk8892rbji",
    "nickname": "Main office",
    "companyName": "We Ship You Corp",
    "name": "John Doe",
    "taxId": "88-1345985",
    "email": "john.doe@weshipyou.com",
    "phone": "+1 (786) 651-0451",
    "isResidential": false,
    "status": "active",
    "address": {
      "uid": "e9j57zlvd0z8",
      "houseNumber": "924",
      "road": "nw 36 ave",
      "unit": null,
      "city": {
        "name": "Homestead",
        "state": {
          "name": "Florida",
          "isoCode": "FL",
          "country": {
            "isoCode": "US",
            "name": "United States"
          }
        }
      },
      "postal_code": {
        "postalCode": "33033"
      }
    }
  },
  "createdAt": "2026-11-01T00:37:51.000Z",
  "updatedAt": "2026-11-01T00:37:52.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Delete a shipment

DELETE/shipments/{shipmentId}

Requires an access token

Deletes a shipment that has no label yet (state created). To cancel a shipment whose label is already bought, use DELETE /shipments/labels/{trackingNumber}.

Path parameters

shipmentIdstringrequired
The shipment uid, or its WeShipYou tracking number (WSY…).

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

The deleted shipment

The Shipment object

400

The shipment cannot be deleted in its current state

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

404

No shipment has that id

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

DELETE/shipments/{shipmentId}

curl -X DELETE 'https://sandbox.weshipyou.com/api/v1/shipments/{shipmentId}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "uid": "wwbvygom0rlz",
  "state": "created",
  "statusTracking": "in transit",
  "transactionState": null,
  "externalReferenceCode": "shp1x6",
  "externalCustomerId": null,
  "externalUniqueId": null,
  "incoterms": "DDU",
  "weightUnit": "gm",
  "dimUnit": "cm",
  "weight": 1000,
  "length": 10,
  "width": 10,
  "height": 10,
  "totalValue": 10,
  "insurance": 0,
  "insuranceAmount": null,
  "sellerNotes": null,
  "buyerNotes": null,
  "labelCreatedAt": null,
  "deliveredAt": null,
  "cancellationReason": null,
  "cancellationReasonCode": null,
  "createdAt": "2026-11-01T00:37:50.000Z",
  "updatedAt": "2026-11-01T00:37:50.000Z"
}

Try itSend a real request to Test from this page. No code needed.

Get shipment categories

GET/shipments/categories

Requires an access token

Lists the content categories a parcel item can declare.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

A page of shipment content categories.

totalintegerrequired
Total number of matching records.
limitintegerrequired
Page size used for this response.
skipintegerrequired
Number of records skipped before this page.
dataarray of Categoryrequired
The Category object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

Forbidden

GET/shipments/categories

curl 'https://sandbox.weshipyou.com/api/v1/shipments/categories' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "total": 30,
  "limit": 500,
  "skip": 0,
  "data": [
    {
      "uid": "u40h56jccmdi",
      "name": "Phone Accessory (no battery)",
      "slug": "accessory_no_battery",
      "weight": null,
      "length": null,
      "width": null,
      "height": null,
      "containsDocuments": 0,
      "containsOtherDg": 0,
      "containsLiquids": 0,
      "containsBatteryPi967": 0,
      "containsBatteryPi966": 0,
      "containsBatteryPi965": 0,
      "parentId": null
    }
  ]
}

Try itSend a real request to Test from this page. No code needed.

Get country categories

GET/shipments/country-categories

Requires an access token

Lists the content categories a destination country uses for customs.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

A page of country-specific content categories.

totalintegerrequired
Total number of matching records.
limitintegerrequired
Page size used for this response.
skipintegerrequired
Number of records skipped before this page.
dataarray of Country categoryrequired
The Country category object

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

Forbidden

GET/shipments/country-categories

curl 'https://sandbox.weshipyou.com/api/v1/shipments/country-categories' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "total": 0,
  "limit": 500,
  "skip": 0,
  "data": []
}

Try itSend a real request to Test from this page. No code needed.

Buy labels

POST/shipments/labels

Requires an access token

Buys the label of one or more shipments at the rate you chose. The charge is booked in your WeShipYou wallet: your balance is used first and only the remainder is charged to paymentMethod.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

accountIdstring
Account uid, account number (CU…) or external account number.
paymentMethod"credit_line" | object
How to pay what your wallet balance does not cover: "credit_line" for accounts with a credit line, or a saved card as { "paymentMethodId": "pm_…" }. Can be omitted when the balance covers the whole amount.
Child attributes
One of
Allowed values:credit_line
paymentMethodIdstring
usePointsboolean
Spend your WeShipYou points first.
insuranceboolean
Insure every shipment of this purchase (true) or none of them (false). Leave it out to keep each shipment’s own insurance.
handoverOptionsarray of objectrequired
Child attributes
- handoverOptionstringrequired
  Allowed values:dropoffpickup
- pickupDatestring <date>
- pickupTimestring
- shipmentsarray of objectrequired
  Child attributes
  shipmentIdstringrequired
  Shipment uid or WeShipYou tracking number.
  rateIdstringrequired
  The uid of the chosen rate of that shipment.

Responses

201

The outcome of each label batch

statusstringrequired
Outcome of the batch.
Allowed values:fulfilledrejected
reasonany
Why the batch failed, when status is rejected.

400

Invalid request, payment not found or insufficient funds

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

POST/shipments/labels

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments/labels' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "CU1234567",
  "paymentMethod": "credit_line",
  "usePoints": true,
  "insurance": false,
  "handoverOptions": [
    {
      "handoverOption": "dropoff",
      "pickupDate": "2026-10-02",
      "pickupTime": "10:00",
      "shipments": [
        {
          "shipmentId": "6f1c2b8e-3d4a-4f5b-9c6d-7e8f9a0b1c2d",
          "rateId": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e"
        }
      ]
    }
  ]
}'

Response

[
  {
    "status": "fulfilled"
  }
]

Try itSend a real request to Test from this page. No code needed.

Cancel a label

DELETE/shipments/labels/{trackingNumber}

Requires an access token

Cancels a label the carrier has not picked up yet. What you paid for it is credited back to your WeShipYou wallet.

Path parameters

trackingNumberstringrequired
The WeShipYou tracking number of the label.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Responses

200

The label was cancelled

idstringrequired
WeShipYou tracking number of the cancelled label.

400

The label can no longer be cancelled

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

401

Missing or invalid access token

namestring
Always NotAuthenticated
messagestring
codenumber
Always 401
classNamestring
Always not-authenticated
dataobject

403

You do not have access to this account

namestring
Always Forbidden
messagestring
codenumber
Always 403
classNamestring
Always forbidden
dataobject

404

Not found

namestring
Always NotFound
messagestring
codenumber
Always 404
classNamestring
Always not-found
dataobject

409

The shipment changed state while cancelling; retry

namestring
Always Conflict
messagestring
codenumber
Always 409
classNamestring
Always conflict
dataobject

DELETE/shipments/labels/{trackingNumber}

curl -X DELETE 'https://sandbox.weshipyou.com/api/v1/shipments/labels/{trackingNumber}' \
  -H "Authorization: Bearer $WSY_ACCESS_TOKEN"

Response

{
  "id": "WSYOP5B60J3SCU"
}

Try itSend a real request to Test from this page. No code needed.

Confirm a delivery

POST/shipments/confirm-delivery

No access token needed

Records that the recipient received a shipment that is in transit or delivered. No access token is needed: the tracking number and the account number identify the shipment.

Header parameters

Accept-Languagestring
Two-letter code of the language for messages: en, es or pt.
Default: en-US

Request bodyapplication/json

trackingNumberstringrequired
accountNumberstringrequired
The account number of the shipment owner (CU…).

Responses

201

Delivery recorded

okboolean
Always true
idstring
The tracking number.

400

Missing fields, unknown account or shipment, or a shipment that is not in transit

namestring
Always BadRequest
messagestring
codenumber
Always 400
classNamestring
Always bad-request
dataobject

POST/shipments/confirm-delivery

curl -X POST 'https://sandbox.weshipyou.com/api/v1/shipments/confirm-delivery' \
  -H "Content-Type: application/json" \
  -d '{
  "trackingNumber": "WSY0000000000US",
  "accountNumber": "CU1234567"
}'

Response

{
  "ok": true,
  "id": "WSYZD8KI41VSCU"
}

Try itSend a real request to Test from this page. No code needed.