# Sendle Developer Hub Documentation ## Guides - [250g Pouch](https://developers.sendle.com/docs/250g.md) - [Unlimited Satchel](https://developers.sendle.com/docs/unlimited-satchels.md) - [Becoming a partner](https://developers.sendle.com/docs/becoming-a-partner.md) - [Integration Best Practices](https://developers.sendle.com/docs/integration-best-practices.md) - [Offline / Manual Billing](https://developers.sendle.com/docs/partner-offline-billing.md) - [Glossary](https://developers.sendle.com/docs/glossary.md) - [Products](https://developers.sendle.com/docs/products.md) - [Regional API Differences](https://developers.sendle.com/docs/regional-api-differences.md) ## API Reference - [Cancel an Order](https://developers.sendle.com/reference/cancelorder.md): Cancels the given order. An order can be cancelled so long as it hasn't been collected by a driver. The way to see whether an order can still be cancelled is with the `is_cancellable` key when [viewing an order](ref:vieworder). If the order has **already been cancelled** a `200` response will be returned – this is why an [idempotency key](ref:idempotency-keys) isn't needed for this endpoint. If the order has already been **collected** a `422` failure response will be returned. Note: Cancelled orders aren't deleted from the system and should still be viewable on your dashboard in the 'cancelled' state. - [Create an order](https://developers.sendle.com/reference/createorder.md): Creates an order to ship a parcel to the given delivery address. You can send parcels domestically inside Australia, Canada, and the United States. International parcels can be shipped from Australia and the United States to countries around the globe, or from Canada to the United States. With our API you can tell us the parcel size, origin, and destination, and we'll do the work to find the best route and price for your order. ----- Since this is a `POST` request, the params need to be sent in the **body** of your request as a **JSON object**. Fill out some fields below and see how the data is sent in the request example box. If you need more information on GET vs POST requests, the Mozilla MDN [has a nice summary](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ----- We decide which currency to charge based on where the parcel is being sent from, so `AUD` for Australian, `CAD` for Canadian, and `USD` for U.S. parcels. This is the currency you'll be charged in. You'll need a card for the currency you're creating orders in, so an [AUD credit card](https://app.sendle.com/dashboard/billing?currency=AUD), [CAD credit card](https://app.sendle.com/dashboard/billing?currency=CAD), or a [USD credit card](https://app.sendle.com/dashboard/billing?currency=AUD). If you don't have the correct currency enabled for your card then you'll receive an error in the response. ----- Here are a few things to keep in mind while using this endpoint: - A valid postcode **and** suburb name must be given. The suburb name is validated against the postcode, and they must match. - Make sure you send the `Content-Type: application/json` header, since you're sending the JSON body. - Look at the [Parcel Weights and Dimensions](ref:parcel-weights-and-dimensions) page for advice on parcel sizes. - Look at the [First Mile](ref:first-mile) page to see how parcels enter our mail network. - **All strings (names, addresses, …) must include only [Latin characters](https://support.sendle.com/hc/en-au/articles/115002794031-International-Book-with-Latin-characters).** That's A-Z along with certain accented characters like á, é, í, ó, and ú. Characters may show without accents on the physical label, but this will not affect deliverability. - If the `product_code` parameter is not given, the `product` object may not be included in the response. And when sending international orders: - Canadian international orders can only be sent to the United States. - Australian and Canadian international orders can only be [picked up](ref:first-mile). - When sending from Australia, identification matching the sender name on the label must be provided for the first three pickups of international parcels. This means **the first three times international parcels get picked up,** and not the first three international parcels sent. - The sender name can't be a URL (or URL-like, e.g. `Example.com`) because of shipping restrictions. - [HS codes](https://en.wikipedia.org/wiki/Harmonized_System) (in `parcel_contents`) are required when sending internationally. Senders can [lookup 6-digit codes here](https://uscensus.prod.3ceonline.com/). ----- You can prevent duplicate orders by including an [idempotency key](ref:idempotency-keys) when sending requests to this endpoint. While testing idempotency keys, pressing 'Try It!' every time will show you a new response for each request. If the response doesn't change, that means you were sent the same response and your idempotency key is working. - [Get products](https://developers.sendle.com/reference/getproducts.md): Returns how much you'll expect to pay to send a parcel, given the shipping details and your current plan. You'll receive one quote for each shipping product Sendle supports for the given route. Products are separated by details like service type (e.g. Standard vs Express) and first-mile option (whether a driver will pickup the parcel or the sender will drop it off at a valid Sendle location). When booking the delivery with a quote from this endpoint, you **need to send the selected product code** along with your order. You can get quotes for both domestic and international shipments. International parcels can be shipped by the Sendle Duties Unpaid (DAP) service from Australia and the United States to many countries around the globe, or from Canada to the United States. This endpoint does **not** support shipping Duties Paid (DDP Price Guaranteed) international orders. Use the `POST` version of this endpoint if you require that service. Note that not all countries can be shipped to with the Sendle Duties Unpaid service. ----- Since this is a `GET` request, the params need to be sent in the **query string**, not in the body like the [create an order](ref:createorder) endpoint requires. The `?` in the URL starts the query string. Be sure to separate terms using `=` pairs in the query string, and use [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters) for all spaces or special characters like the playground on the right shows. You can type some spaces and special characters into the boxes below to see how they get encoded! If you need more information on `GET` vs `POST` requests, Mozilla's MDN [has a nice summary](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ----- Here are a few things to keep in mind while using this endpoint: - Filter the returned list according to the user’s configuration (e.g. your integration may select whether to show the pickup or drop off “Sendle Standard” product). - Display all valid quotes with the included product names (e.g. **“Sendle Standard”**, **“Sendle Express”**). - Look at the [Parcel Weights and Dimensions](ref:parcel-weights-and-dimensions) page for advice on parcel sizes. - Look at the [First Mile](ref:first-mile) page to see how parcels enter our mail network. - We decide which currency to return based on where the parcel is being sent from, so `AUD` for Australian, `CAD` for Canadian, and `USD` for U.S. parcels. This is the currency you'll be charged in. - The ETAs returned by this endpoint are the number of **business days** until the parcel should be delivered. - [Get a quote (deprecated)](https://developers.sendle.com/reference/getquote.md): Returns how much you'll expect to pay to send a parcel, given the shipping details and your current plan. You can get quotes for both domestic and international shipments. International parcels can be shipped from Australia and the United States to countries around the globe, or from Canada to the United States. > 🚧 New product-aware quoting > > Your system should use the new [Get Products endpoint](ref:getproducts) instead of this endpoint. This new endpoint makes quoting easier and also lets your system see all available [shipping products](doc:products) (such as Sendle Express or Saver). > > For more information, see [the post detailing our quoting update](https://developers.sendle.com/changelog/api-products-endpoint). ----- Since this is a `GET` request, the params need to be sent in the **query string**, not in the body like the [create an order](ref:createorder) endpoint requires. The `?` in the URL starts the query string. Be sure to separate terms using `=` pairs in the query string, and use [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters) for all spaces or special characters like the playground on the right shows. You can type some spaces and special characters into the boxes below to see how they get encoded! If you need more information on `GET` vs `POST` requests, Mozilla's MDN [has a nice summary](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ----- Here are a few things to keep in mind while using this endpoint: - Look at the [Parcel Weights and Dimensions](ref:parcel-weights-and-dimensions) page for advice on parcel sizes, including using our AU Domestic Unlimited Satchels. - Look at the [First Mile](ref:first-mile) page to see how parcels enter our mail network. - We decide which currency to return based on where the parcel is being sent from, so `AUD` for Australian, `CAD` for Canadian, and `USD` for U.S. parcels. This is the currency you'll be charged in. - The ETA returned by this endpoint is the number of **business days** until the parcel should be delivered. - [Getting Printable Labels](https://developers.sendle.com/reference/getting-labels.md) - [Serviceable products](https://developers.sendle.com/reference/postproducts.md): Returns how much you'll expect to pay to send a parcel, given the shipping details and your current plan. You'll receive one quote for each shipping product Sendle supports for the given route. Products are separated by details like service type (e.g. Standard vs Express) and first-mile option (whether a driver will pickup the parcel or the sender will drop it off at a valid Sendle location). You can get quotes for both domestic and international shipments. There are two international services offered by Sendle: - Sendle Duties Unpaid (DAP): from Australia and the United States to many countries around the globe, or from Canada to the United States. Duties & taxes are **not** included in these service quotes. This means that your receiver may be subject to paying import duties on receiving the parcel. We cannot ship to some countries with the DAP service. - Duties Paid (DDP Price Guaranteed): from Australia to the United States, with more supported countries coming soon. Duties & taxes are included in quotes made with this service. ----- Since this is a `POST` request, the params need to be sent in the **body** of your request as a **JSON object**. Fill out some fields below and see how the data is sent in the request example box. If you need more information on GET vs POST requests, the Mozilla MDN [has a nice summary](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ----- Here are a few things to keep in mind while using this endpoint: - Filter the returned list according to the user’s configuration (e.g. your integration may select whether to show the pickup or drop off “Sendle Standard” product). - Display all valid quotes with the included product names (e.g. **“Sendle Standard”**, **“Sendle Express”**). - Look at the [Parcel Weights and Dimensions](ref:parcel-weights-and-dimensions) page for advice on parcel sizes. - Look at the [First Mile](ref:first-mile) page to see how parcels enter our mail network. - We decide which currency to return based on where the parcel is being sent from, so `AUD` for Australian, `CAD` for Canadian, and `USD` for U.S. parcels. This is the currency you'll be charged in. - The ETAs returned by this endpoint are the number of **business days** until the parcel should be delivered. When sending international orders via the Duties Paid (DDP Price Guaranteed) service: - Only the POST version of this endpoint supports Duties Paid (DDP Price Guaranteed) for international shipments. - [10-digit HS codes](https://en.wikipedia.org/wiki/Harmonized_System) (in `parcel_contents`) are required for each item being shipped to determine accurate duties and taxes. Senders can [lookup 10-digit codes here](https://uscensus.prod.3ceonline.com/). - [View an Order](https://developers.sendle.com/reference/vieworder.md): Returns the given order including its status, the public tracking URL, and the metadata you passed when creating it. Viewing an order should include everything that you need to know about it! Aside from the [tracking endpoint](ref:trackparcel), of course. Importantly, the `is_cancellable` key under the `scheduling` section tells you whether you can [cancel the order](ref:cancelorder). - [Return an order](https://developers.sendle.com/reference/returnorder.md): Creates a return label, letting receivers easily send orders back to the original sender. Senders can use this endpoint to prepare an order to be returned. Returns can only be placed for domestic orders. After creating the return order, you can [get a label](ref:getting-labels) using the URLs in the response. The sender can then include the return label in the parcel before it's shipped (because they aren't added to your invoice until they're used), or send the label file to the customer for them to print it out. If the receiver will be printing it, try to use A4/Letter sizes since most receivers don't have dedicated label printers. If you want a convenient page receivers can read – which includes packaging directions – here are our [AU Returns](https://support.sendle.com/hc/en-au/articles/4416750997389-How-to-return-a-parcel) and [US Returns](https://support.sendle.com/hc/en-us/articles/4416750997389-How-to-return-a-package) articles. After attaching the return label to the parcel, the receiver will need to leave the parcel at a [valid drop off location](https://returns.sendle.com/). ----- Since this is a `POST` request, the params need to be sent in the **body** of your request as a **JSON object**. Fill out some fields below and see how the data is sent in the request example box. If you need more information on GET vs POST requests, the Mozilla MDN [has a nice summary](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ----- Returns are [idempotent by nature](ref:idempotent-endpoints) – sending a new return request will give you the details of the already-created return order. The customer reference and delivery instructions given on the first request will be used and can't be updated, so make sure they're right the first time. - [View a return order](https://developers.sendle.com/reference/viewreturnorder.md): Views the given return order, including the label URLs. You can [get a label](ref:getting-labels) using the URLs in this response. The sender can then include the return label in the parcel before it's shipped (because they aren't added to your invoice until they're used), or send the label file to the customer for them to print it out. If the receiver will be printing it, try to use A4/Letter sizes since most receivers don't have dedicated label printers. If you want a convenient page receivers can read – which includes packaging directions – here are our [AU Returns](https://support.sendle.com/hc/en-au/articles/4416750997389-How-to-return-a-parcel) and [US Returns](https://support.sendle.com/hc/en-us/articles/4416750997389-How-to-return-a-package) articles. After attaching the return label to the parcel, the receiver will need to leave the parcel at a [valid drop off location](https://returns.sendle.com/). - [Create shipping manifest](https://developers.sendle.com/reference/createshippingmanifest.md): Creates shipping manifest(s) for the given orders. Shipping manifests let a driver collect multiple parcels while scanning one barcode on US Domestic orders. Today we have one type of shipping manifest – [USPS SCAN Forms](https://faq.usps.com/s/article/Click-N-Ship-SCAN-Form). > 📘 Info > > Since this is a `POST` request, the params need to be sent in the **body** of your request as a **JSON object.** The mdn web docs have a [summary of HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ----- Keep these in mind while generating shipping manifests: - Only orders with a USPS label can currently be included on shipping manifests. - Each order can only be included on a single shipping manifest. - Shipping manifests cannot be modified after being created. - More than one shipping manifest may be returned by this endpoint. - Each order must be created **the same day as the shipping manifest.** The pickup / drop-off date can be in the future, but the order must be **created** on the same day as the shipping manifest. > 👍 End-of-day manifesting > > Since shipping manifests can only be created for orders booked that day, encourage your senders to generate and print their manifests at the end of each day. > 🗒️ Multi-page shipping manifests > > A single shipping manifest may include more than one SCAN form. In this case, the PDF will have multiple pages. > > Note: > > - Print and include all pages when giving a shipping manifest to the driver or when dropping the parcels off. > - Ensure the driver scans each page of the shipping manifest. > - **All orders on a single shipping manifest must be collected at the same time.** ----- If an order has **already been manifested** a `422` response will be returned – this is why an [idempotency key](https://developers.sendle.com/reference/idempotency-keys) isn't needed for this endpoint. - [Download shipping manifest](https://developers.sendle.com/reference/downloadshippingmanifest.md): Returns the printable shipping manifest. Shipping manifests let a driver collect multiple parcels while scanning one barcode on US Domestic orders. Today we have one type of shipping manifest – [USPS SCAN Forms](https://faq.usps.com/s/article/Click-N-Ship-SCAN-Form). ----- This endpoint returns a PDF of the given shipping manifest, which can be printed. - [Get orders on shipping manifest](https://developers.sendle.com/reference/getshippingmanifestorders.md): Returns all orders on a shipping manifest. Shipping manifests let a driver collect multiple parcels while scanning one barcode on US Domestic orders. Today we have one type of shipping manifest – [USPS SCAN Forms](https://faq.usps.com/s/article/Click-N-Ship-SCAN-Form). ----- This endpoint returns all orders that are on the given shipping manifest. - [Get all shipping manifests](https://developers.sendle.com/reference/getshippingmanifests.md): Returns all shipping manifests for your account. Shipping manifests let a driver collect multiple parcels while scanning one barcode on US Domestic orders. Today we have one type of shipping manifest – [USPS SCAN Forms](https://faq.usps.com/s/article/Click-N-Ship-SCAN-Form). ----- This endpoint returns all shipping manifests for your account, including ones created via the API and also the Sendle dashboard. - [Get status of shipping manifest](https://developers.sendle.com/reference/getshippingmanifeststatus.md): Returns status of a shipping manifest. Shipping manifests let a driver collect multiple parcels while scanning one barcode on US Domestic orders. Today we have one type of shipping manifest – [USPS SCAN Forms](https://faq.usps.com/s/article/Click-N-Ship-SCAN-Form). ----- This endpoint returns the status and other metadata of the given shipping manifest. - [Basic API Test](https://developers.sendle.com/reference/ping.md): Returns a simple response and a timestamp showing when it was generated on our system. You can use this endpoint to test your [API credentials](ref:getting-your-api-key), [idempotency keys](ref:idempotency-keys), and make sure you're ready to explore the rest of Sendle's API endpoints. ----- While testing idempotency keys, pressing 'Try It!' every time will show you a new response for each request. If the response doesn't change, that means you were sent the same response and your idempotency key is working. - [Subscribe to tracking events for a parcel](https://developers.sendle.com/reference/subscribetotrackingevents.md): This endpoint allows a user to subscribe to tracking events via webhooks for a specific parcel, identified by its Sendle reference (ref). Once subscribed, the user will receive real-time tracking updates via webhooks to the callback endpoint url on the account. The initial response to this subscription request will include all existing tracking events associated with the parcel. Webhook events are only sent for updates that occur after the subscription is created. **Note:** A webhook endpoint must be registered on the account before a subscription can be created. You can add a callback endpoint url through the account dashboard under Settings --> API. ----- Here's most of our tracking events and what they mean: | Tracking Event | Description | | :-: | --- | | **Pickup Attempted**| Driver attempted to pickup the parcel. | | **Pickup** | Parcel successfully picked up. | | **Drop Off** | Parcel has not yet been dropped off. | | **Dropped Off** | Parcel left at a drop-off location. | | | | | **Info** | Information about the parcel. This can come from us or the delivery partner. | | **In Transit** | Parcel in transit between hub locations. | | | | | **Out for Delivery** | Driver has the parcel and is taking it to be delivered. | | **Delivery Attempted** | Parcel delivery attempted, but unsuccessful. | | **Delivered** | Parcel successfully delivered. | | **Local Delivery** | Delivery is being handled by a local partner (e.g. a local postal service or similar). | | **Card Left** | Parcel delivery attempted and a card has been left for the receiver to arrange collection or re-delivery. | | **Left with Agent** | Parcel has been left with a parcel connect location, POPStation, or similar for collection. | | | | | **Damaged** | Parcel has been marked as damaged. | | **Unable to Deliver** | Parcel could not be delivered. | | **Expired** | The label for this parcel has expired. | If you receive an event type not on this list, look at the `description` of the event for more information. - [Webhooks](https://developers.sendle.com/reference/tracking-webhooks.md) - [Track a Parcel](https://developers.sendle.com/reference/trackparcel.md): Returns tracking details for the given parcel, including when different events happened to it. This endpoint doesn't contain precise personal location information, but can contain the city where events happen and some names (e.g. 'Parcel was signed for by JIMMY'). To get the public tracking URL that can be shared with the receiver, see the `tracking_url` key in the response from the [create](ref:createorder) or [view an order](ref:vieworder) endpoints. Note: The Sendle API does not currently expose webhooks, and this endpoint is the only way to retrieve tracking information. For updates, keep an eye on [our Changelog](https://developers.sendle.com/changelog)! ----- We recommend getting new tracking information for each parcel once per hour. You should limit your requests to this endpoint to 10 per second per unique IP. If you need a higher limit, reach out [to our team](mailto:api@sendle.com). ----- Here's most of our tracking events and what they mean: | Tracking Event | Description | | :-: | --- | | **Pickup Attempted**| Driver attempted to pickup the parcel. | | **Pickup** | Parcel successfully picked up. | | **Drop Off** | Parcel has not yet been dropped off. | | **Dropped Off** | Parcel left at a drop-off location. | | | | | **Info** | Information about the parcel. This can come from us or the delivery partner. | | **In Transit** | Parcel in transit between hub locations. | | | | | **Out for Delivery** | Driver has the parcel and is taking it to be delivered. | | **Delivery Attempted** | Parcel delivery attempted, but unsuccessful. | | **Delivered** | Parcel successfully delivered. | | **Local Delivery** | Delivery is being handled by a local partner (e.g. a local postal service or similar). | | **Card Left** | Parcel delivery attempted and a card has been left for the receiver to arrange collection or re-delivery. | | **Left with Agent** | Parcel has been left with a parcel connect location, POPStation, or similar for collection. | | | | | **Damaged** | Parcel has been marked as damaged. | | **Unable to Deliver** | Parcel could not be delivered. | | **Expired** | The label for this parcel has expired. | If you receive an event type not on this list, look at the `description` of the event for more information. - [Unsubscribe to tracking events for a parcel](https://developers.sendle.com/reference/unsubscribetotrackingevents.md): This endpoint allows a client to unsubscribe from tracking event webhooks for a given parcel identified by its Sendle reference (ref). After unsubscribing, the user will no longer receive webhook notifications for that parcel's tracking events. This action only affects the authenticated user's subscription and does not impact the tracking status or delivery of the parcel. - [Dashboard Billing CSV](https://developers.sendle.com/reference/dashboard-billing-csv.md) - [Authenticating API Requests](https://developers.sendle.com/reference/authentication.md) - [Getting Your API Key](https://developers.sendle.com/reference/getting-your-api-key.md) - [Order States and Flow](https://developers.sendle.com/reference/order-states.md) - [Parcel Weight and Volume](https://developers.sendle.com/reference/parcel-weights-and-dimensions.md) - [Sendle's Sandbox Server](https://developers.sendle.com/reference/sendles-sandbox-server.md) ## Recipes - [Book an order](https://developers.sendle.com/recipes/book-an-order.md) - [Confirm API credentials](https://developers.sendle.com/recipes/confirm-api-credentials.md) - [Generate Authorised Tracking URL](https://developers.sendle.com/recipes/generate-authorised-tracking-url.md) - [Getting a product's receiver-friendly name](https://developers.sendle.com/recipes/getting-a-products-receiver-friendly-name.md) - [Retrieve label URL](https://developers.sendle.com/recipes/retrieve-label-url.md) ## Changelog - [Webhooks for tracking parcels now available](https://developers.sendle.com/changelog/webhooks-for-tracking-parcels-now-available.md) - [New Product Code for international shipping](https://developers.sendle.com/changelog/new-product-code-for-international-shipping.md) - [New Product for Canada domestic shipping](https://developers.sendle.com/changelog/new-product-for-canada-domestic-shipping.md) - [HS Code requirement changes for CA International](https://developers.sendle.com/changelog/hs-codes-requirement-changes-for-ca-international.md) - [Sunsetting the Get a Quote endpoint](https://developers.sendle.com/changelog/sunsetting-get-a-quote-endpoint.md)