Here are some guidelines to help ensure your integration works the best it can for you, for Sendle, and for your customers.

Although these are not mandatory for integrations, these best practices illustrate the approach that typically results in the best user experience and easiest implementation path. They should be the default approach, and your integration should only stray from these guidelines when strictly necessary.

If these practices don't work for your product or users, reach out to our Partnerships team so we can help by suggesting different approaches.

Sender Onboarding

Verify the Sender Email

A valid, working Sender Email is essential to ensure a smooth Sendle experience. This is used in several places:

• We will communicate with the sender via email in case of any pickup or delivery issues.
• The Sender Email is also essential to our International pickup process, which has strict security requirements.
• We will also use this email to identify an account, if we need to escalate to your team.

❗️

We strongly discourage using a generic support email, per-order emails, or intermediated email addresses – these can cause delays, formatting problems, or duplicated emails.

Ensure Compliance for T&Cs and Dangerous Goods

As users will be booking with your account, you need to make sure they adhere to our strict requirements around dangerous goods. It’s important to make sure users are informed of these, and honour them.

You can read more here:

📘

If a user breaches the Sendle T&Cs or Dangerous Goods policies, we may ask you to disable that account's access to Sendle.

Checkout

Select Suburb / Postcode / ZIP from Sendle's list

To ensure the best chance of a seamless label booking experience, use a dropdown to ensure that all pickup / suburb pairs match with Sendle’s list. This prevents typos and mis-matching data, which can prevent a label from being booked.

Free-text suburb / postcode fields at checkout can be particularly problematic unless the Sender can override or correct these. For example, a customer may mis-spell their suburb, use the wrong post code, or use an unofficial suburb name which is not recognised by the API.

These lists can be found here:

• Australia: Pickup, National and Remote suburb lists
• Canada: Pickup and delivery postal codes list
• USA: Standard USPS ZIP code lists, with these restrictions considered.

Collect Full Receiver Information at Checkout

High quality information helps increase the likelihood of a parcel being delivered successfully on the first attempt. This includes:

• Contact Name
• Email (required)
• Company Name
• Phone (strongly encouraged)
• Instructions (where possible)

For parcels within Australia, you may want to ensure senders use industry standard terms like “Authority To Leave” or “Signature on Delivery” to help make sure the correct action is taken by drivers.

Carefully Estimate Weight and Volume

Understand your merchants to ensure they're booking parcels at the correct dimensions. This helps protect merchant revenue by avoiding underquoting shipping costs.

Some common considerations:

• If customers can purchase multiple items, ensure the correct quantity is used when estimating weight and volume.
• Understand how senders pack their items, and how this may affect the total volume.
• Understand how senders may need to split items across multiple parcels, for larger orders.
• Understand the impact of any Under-declared Adjustments if a parcel is not booked correctly. Some integrations may allow that cost to be passed on to the receiver, but that is not always the case.

Fetch Live Quotes and Minimise Caching

Only fetch quotes from the API when needed, and use those results immediately or only cached for a few minutes.

We frequently optimise our network with new data and based on historical performance, and this means quotes can change. This can cause confusion if a quote returns one result, but booking the order returns a different one.

Although major changes such as rate changes and zone changes only happen a few times a year, changes to our ETAs and suburb serviceability happens much more frequently. This is particularly true during major events such as holiday periods, major highway/railway/air traffic disruption, or natural disasters.

Fetch Quotes for the Specific Account

The unauthenticated Quote endpoint is deprecated and no longer documented. If your system is calling the API in this way, it should move to making authenticated quote requests instead.

By making authenticated quote requests, the correct quote for the account's current plan will be returned. This means a plan change on Sendle (including an upgrade or downgrade) will immediately be applied to your integration with no work needed from you or the sender.

Requesting a quote using the deprecated plan_name param requires the user to remember to update their configuration on your system when their plan changes. This may result in your system presenting incorrect prices, impacting their sales or margins. Using the plan_name can also cause problems if a we decide to rename a plan, or the account is on a custom plan.

🚧

plan_name is Deprecated

Requesting a quote using the plan_name parameter is deprecated. Please use the authenticated quote endpoint instead.

Ordering & Fulfilment

Send Full Contact Information to the API

High quality information helps increase the likelihood of a parcel being picked up and delivered successfully, on the first attempt.

A few things to keep in mind:

• Include the real Sender and Receiver email and phone numbers, as Sendle and drivers will contact them directly regarding any issues.
• Ensure the address is well formatted and succinct. We recommend keeping Lines 1 and 2 within 40 characters where possible to maximise compatibility.
• A correct delivery name or business name helps increase the chances of pickup and delivery, and prevents delays or errors.
• Avoid duplicating the suburb, postcode, state or country in Line 1 and 2; use only the dedicated fields.
• The receiver's name and business name params both appear on the label, so make sure these aren't duplicates of each other.

❗️

We strongly discourage using a generic support email, per-order emails, or intermediated email addresses – these can cause delays, formatting problems, or duplicated emails.

For Australian orders:

• The Sender Email is essential to our Australian International pickup process, which has strict security requirements.

Understand the Sender's Fulfilment Process

If booking a pickup service, be mindful of the time required for the sender to prepare their parcel.

Less sophisticated senders may need additional time to pick, pack and label before a driver arrives. In these cases, we recommend suggesting a pickup date up to 3 days in the future.

Know when to:

• Recommend drop off rather than pick up.
• Book a parcel automatically, or require manual intervention.
• Book for next day pickup, or allow a date to be specified.
• Provide the label via download or via email.

Consider your user behaviour carefully when implementing the pickup_date Order field, or creating a pickup booking automatically.

The pickup_date defaults to "Next Business Day" if left blank, however this may not be feasible for less sophisticated senders. These users may need additional time to pick and pack their order before the parcel is ready for pickup.

In these cases it can be better require a manual process before calling the Create Order endpoint.

While less sophisticated users may find it simple to download a label from their email, more sophisticated sellers may find this slows their shipping process considerably.

Identify Your Requests to the API

There are two important ways to identify your integration to the Sendle team:

1. Always send a meaningful User-Agent HTTP header in your API requests. This helps our Engineering team quickly identify your traffic so it doesn't get blocked by automated security tools. For example: Your Product (https://www.example.com) is sufficient.
2. Include a partner_id field in the Create Order metadata field with the value we provide. This lets us track your integration volume, and helps us to properly handle an order for support, feedback or optimisation. The value will be provided by your Partner Manager.

Please also include in the metadata anything that helps your team identify a transaction - we can relay this if we need to escalate a query or issue to you. For example, you might send a metadata like:

{
  "metadata" => {
    "partner_id" => "acme-inc",
    "user_id" => "123456",
    "acme_order_id" => "O112233"
  }
}

Allow Choice of Label Sizes

The Sendle API offers two label formats, both using PDF: a full page (A4 or Letter) or cropped.

Less sophisticated or low volume senders will typically use a domestic printer with standard paper. For these users, the full page PDF is perfect as it minimises printer configuration.

Sophisticated senders will often have a label printer. For these users, the cropped labels are typically the easiest.

Do Not Alter Sendle Labels

Do not post-process, resize, or alter Sendle labels. Alterations can cause issues with scanning barcodes, increasing the likelihood of a parcel becoming delayed or lost.

Do not generate your own Sendle labels. We design our labels to work with a range of driver scanners and depot machinery, and labelling requirements can change at short notice. In some cases the label format may need to adhere to specific legal or contractual requirements, and may be rejected if these are not correct. Because our label formats may change at short notice, we also do not recommend extracting details such as barcodes from the labels.

We do not recommend post-processing or altering labels (including rotating, rasterizing, or converting into other formats). Any bugs or errors in this process may result in an incomplete label, resulting in the parcel being refused carriage, or not receiving the correct tracking scans.

In particular – rotating labels can drastically lower the barcode quality on domestic inkjet printers due to the action of the print head. This can cause streaks and alignment issues, preventing labels from being scanned.

Let Senders Cancel an Order

There are a number of reasons why an order may need to be changed, or no longer be required. It’s important to cancel the parcel in these cases to prevent a driver attempting pickup.

Remember that Sendle does not allow a parcel to be changed once it's been created, so any changes to dimensions, weight, or other details will require the original order to be cancelled and a new one created.

Understand How Preferences are Inherited

The Sendle API provides a mechanism for existing Sendle Dashboard users to configure settings such as address privacy on labels.

If a Sender has a Sendle Dashboard account on the exact same email address, any preferences they make there will be inherited by orders created by your API integration. This includes:

• The flag to hide their pickup address, where available.
• Their profile image shown in any Sendle emails to their receivers.

The Sendle Dashboard provides functionality to Hide the Sender Address. Once this is set, the generated label will show a simplified Sender address – perfect for smaller merchants shipping from a home address.

For users to take advantage of this, orders created by your API must have a sender.contact.email exactly matching their Sendle Account. If they have chosen to hide their address, the API will automatically apply to that to the generated label.

While this option can help provide home-based merchants some additional privacy, this isn't appropriate for everyone as it hinders a Return To Sender request.

Tracking & Support

Link to Authorised Tracking Pages

The Authorised Tracking Page lets users self-serve common support tasks, depending on their role in the transaction. This allows users a similar support experience as they would receive when booking a parcel via the Sendle Dashboard, despite booking the order through a partner. These support tools are important as they:

• Improve the user experience, by providing the user with common tools at their fingertips.
• Speed up resolution, by collecting the required information before opening a request.
• Remove this support load from your own team, funnelling the requests directly to Sendle.
• Reduce rework, by allowing Sendle to update processes and launch new tools without any process or development changes on your side.

We recommend showing these authorised links to your authenticated users so that they can perform these actions.

❗️

Never expose signed tracking page links to unauthenticated users, as these pages allow performing actions as the sender or receiver.

Let Sendle Handle What We're Good At

Sendle moves millions of parcels a year, with one of the highest NPS scores in the industry. We know how to deliver great experiences to both senders and receivers – that's why you're integrating with us! But that also means your integration needs to let us do what we're good at. There are a few important areas where your integration can make this better:

• If an order is a Missed Pickup, don't cancel it. For pickup orders we'll schedule another driver for the following day. Subsequent missed pickups may make the order eligible for a refund.
• If an order is a Futile Pickup, don't cancel it. This can be a common scenario for C2C senders who may be experiencing a courier pickup service for the first time. In this case, our team will work with them to ensure they understand the process and can reschedule the pickup.
• If the Pickup Date for an order needs to change, don't cancel it and generate a new label; instead, use our Authorised Tracking Page tools to reschedule the pickup. Asking a user to print a new label is an annoying experience and increases the likelihood of a labelling error, or of the parcel being a subsequent Futile Pickup.

Understand Support Escalations

When using the Authorised Tracking Page, senders and receivers are empowered to initiate support requests with Sendle.

However, certain issues can be escalated by your team to Sendle Support.

Operations & Billing

Disable an Account on Sendle's Request

If a sender has violated Sendle’s terms, we reserve the right to terminate their usage. As their usage is shared under your account, you must provide a way to restrict their access to your integration.

Align Your Rates to Sendle's

Sendle’s loss and damage claim system assumes that the amount paid to Sendle matches the amount paid by the sender. Any mismatch can cause user confusion.

Regularly Reconcile & Process Adjustments

Orders may receive adjustments after being booked, and these need to be passed on to your users too. Promptly returning refunds to users helps to reduce confusion and support requests.

Reconcile your weekly billing report weekly, as soon as possible once the invoice data is available. Make sure you pass on:

• Order costs: calculated at creation time. You may already be tracking these at the point of creation, but it's important to reconcile these numbers to identify integration issues, such as duplicate orders.
• Sendle Extra cover: (where available) calculated at creation time.
• Under-declared Adjustment: when a parcel is found to be physically larger or heavier than the size declared when booking.
• Oversize Penalty Adjustment: when a parcel is found to be larger than the maximum allowed dimensions for the service (either volume or weight).
• Un-cancellation adjustments: when a parcel is cancelled, but the label is used on a parcel.
• Cancellation Refunds: both same-cycle cancellation and refund after invoicing.
• Refunds: may be issued due to delay, loss, or other reasons.

Provide an Itemised Invoice

Many senders take great care in reconciling and auditing their shipping costs, and itemised invoices are a common request.

When you charge your user, we recommend you provide them with a full itemised invoice for all parcels, adjustments and refunds. Sendle is not able to provide this to your users.

Ensure You Receive Billing Notifications

If we are unable to process your payment, your account may become locked after a period of time. This would prevent your users from booking parcels via the integration.

Your notification email can be set in your Account Settings under Billing Email.