The Click & Drop API is an integration that allows you to create orders in Click & Drop via API from your own order management systems. This is suitable for eCommerce companies and websites that do not already have a direct integration with Click & Drop.
Please note that some level of development knowledge is required to import orders into Click & Drop by this method.
For developer documentation, click here: https://api.parcel.royalmail.com/
Contents
- Getting started
- Creating an integration
- Authentication
- Troubleshooting
Getting started
If you use your own order management systems, or you use an eCommerce integration that does not currently have a direct integration to Click & Drop, you can use the Click & Drop API to create orders and retrieve the necessary labels and other documentation within your Click & Drop account.
What the Click & Drop API can do:
- Create one or more orders in Click & Drop
- Retrieve order information from Click & Drop
- Retrieve labels and other shipment documents for OBA accounts
- Reset orders in Click & Drop
- Mark orders as 'Despatched'
- Create and retrieve labels
What the Click & Drop API cannot do:
- Retrieve labels and other documents for OLP accounts
Creating an integration
To begin, log in to your Click & Drop account, and navigate to 'Settings' > 'Integrations'.
From the list that appears, select 'Click & Drop API'.
You will be presented with several integration settings:
Default trading name
Select your default trading name from the drop down list. If you only have one trading name, it will be automatically entered. This trading name will determine the return address that is displayed on your labels.
Integration name
Choose the name your integration will be displayed under within Click & Drop.
Use shipping address for billing address
Click & Drop allows you to map both shipping and billing address data. If you select this option, you will only need to map the fields for shipping address data. This option is selected by default.
Create batches for the imported orders
Click this option if you wish for your imported orders to be automatically placed in batches. This occurs per API call, so if your API call contains 5 orders, all five will be placed in a single batch.
Click the 'Update' button when you are ready.
A row for your integration will be visible in your 'Integrations' page grid. Click the row to expand the grid. From here you can edit your integration settings, and view your authentication key.
Please note that only one Click & Drop API integration can be created per account. Should you wish to import orders with a different trading name or company identity, you will need to specify this information in the call itself, see section 4 below.
Authentication
Developers, click here for developer docs: https://api.parcel.royalmail.com/
The Click & Drop API uses API keys to authenticate requests.
From the integration settings page within Click & Drop, click your Click & Drop API integration to expand the row. Your authorisation (auth) key will be displayed here.
It is important that you keep your API key secret and do not share it publicly.
You will need to pass this auth key in the header of every API call made to Click & Drop. Any API requests made without authorisation will fail.
curl --location --request POST 'https://api.parcel.royalmail.com/api/v1/Orders' \
--header 'Authorization: aaaaaa-bbbb-cccc-dddd-eeeeeeee' \
--header 'Content-Type: application/json' \
If you delete and create a new integration to the Click & Drop API, you will be issues a new API key; you will need to update your headers, replacing your old API key.
Troubleshooting
What is the baseURL?
The baseURL for creating orders is https://api.parcel.royalmail.com/api/v1
Please note that this will change as future versions of the API are released.
How many orders can I import?
You can include up to 2000 orders on a single request. Please note that larger requests may take longer to process. Accounts are limited to 2 API calls per second.
Explanation of error codes
400 - Bad Request (Request has missing or invalid parameters and cannot be parsed)
This error usually means some invalid data has been passed. Check the response received for further information about individual fields.
401 - Unauthorised
This error usually means the has been an issue with your auth key. Either the auth code does not match, or was not passed in the header.
403 - Forbidden
This error usually means you are attempting to access an endpoint that is forbidden for your account type.
500 - Internal server error
This error usually means a connection could not be established. Check the health of your connection, and check our status page where any known issues with Click & Drop will be posted.
Minimum system requirements
If you are using browsers or software on Windows machines, please ensure that the system, device, or browser you are using supports Transport Layer Security (TLS) version 1.2 or higher.