How to import orders with the Click & Drop API

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 also suitable for eCommerce companies and websites that do not already have a direct integration with Click & Drop.

Please note that this integration is currently in the testing stages, and will not appear in your account yet. We will announce on our Latest Updates pages once this integration is publicly available. 

For developer documentation, click here: https://api.parcel.royalmail.com/

Contents:

  1. Getting started
  2. Creating an integration
  3. Authentication
  4. Actions
    4a. Create order
    4b. Get order
  5. Troubleshooting

1. Getting started

If you use your own order management systems, or you use an eCommerce integration which does not currently have a direct integration to Click & Drop, you can use the Public API to create orders within your Click & Drop account.

What the public API can do: 

  • Create one or more orders in Click & Drop
  • Retrieve order information from Click & Drop

What the Public API cannot do:

  • Retrieve labels

2. Creating an integration

To begin, log into your Click & Drop account, and navigate to 'Settings' > 'Integrations'.

IntegrationsBlank.png

From the list that appears, select 'Click & Drop API'.

IntegrationBlank.png

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 address book reference: If you have previously added customer details into your Address book, you can enter the Address Book reference into your spreadsheet and select this option. If you do, the address, city, and postcode data will be automatically included with your order. This means you will not have to map those individual fields.

For more information, see this guide: Setting up your address book

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.

Update product data: With this option selected, any product in Click & Drop with the same SKU and name values as a products included with your imported orders will be updated so that values such as weight and package size will be updated to match your imported data.  

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.

IntegrationSettings.png

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. 

APiRow.png

Please note that only one Public 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.

3. Authentication

Developers, click here for developer docs: https://api.parcel.royalmail.com/

The Public API uses API keys to authenticate requests.

From the integration settings page within Click & Drop, click your Public API integration to expand the row. Your authorisation (auth) key will be displayed here. 

IntegrationSettingsPlusAuth.png

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.

Example cURL header:
curl --location --request POST 'https://dev01-cnd-api-gateway-tm.storefeeder.com/api/v1/Orders' \

--header 'Authorization: aaaaaa-bbbb-cccc-dddd-eeeeeeee' \

--header 'Content-Type: application/json' \

4. Actions

Developers, click here for developer docs: https://api.parcel.royalmail.com/

4a. Create order

When creating an order, items must match the specific format. 
Examples and full specifications are displayed in our developer docs.

Multiple items can be sent by nesting multiple sets of item details. 

{
  "items": [
    {
      "orderReference": "string",
      "recipient": {
        "address": {
          "fullName": "string",
          "companyName": "string",
          "addressLine1": "string",
          "addressLine2": "string",
          "addressLine3": "string",
          "city": "string",
          "county": "string",
          "postcode": "string",
          "countryCode": "string"
        },
        "phoneNumber": "string",
        "emailAddress": "string",
        "addressBookReference": "string"
      },
      "sender": {
        "tradingName": "string",
        "phoneNumber": "string",
        "emailAddress": "string"
      },
      "billing": {
        "address": {
          "fullName": "string",
          "companyName": "string",
          "addressLine1": "string",
          "addressLine2": "string",
          "addressLine3": "string",
          "city": "string",
          "county": "string",
          "postcode": "string",
          "countryCode": "string"
        },
        "phoneNumber": "string",
        "emailAddress": "string"
      },
      "packages": [
        {
          "weightInGrams": 0,
          "packageFormatIdentifier": "undefined",
          "dimensions": {
            "heightInMms": 0,
            "widthInMms": 0,
            "depthInMms": 0
          },
          "contents": [
            {
              "name": "string",
              "SKU": "string",
              "quantity": 0,
              "unitValue": 0,
              "unitWeightInGrams": 0,
              "customsDescription": "string",
              "customsCode": "string",
              "originCountryCode": "string"
            }
          ]
        }
      ],
      "orderDate": "2020-07-31T10:01:23.529Z",
      "plannedDespatchDate": "2020-07-31T10:01:23.529Z",
      "specialInstructions": "string",
      "subtotal": 0,
      "shippingCostCharged": 0,
      "total": 0,
      "currencyCode": "string",
      "postageDetails": {
        "sendNotificationsTo": "sender",
        "serviceCode": "string",
        "serviceRegisterCode": "string",
        "consequentialLoss": 0,
        "receiveEmailNotification": true,
        "receiveSmsNotification": true,
        "guaranteedSaturdayDelivery": true,
        "requestSignatureUponDelivery": true,
        "isLocalCollect": true,
        "isDeliveryDutyPaid": true,
        "safePlace": "string",
        "department": "string"
      },
      "tags": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    }
  ]
}

4b. Retrieve orders

By altering the URL, you can retrieve specific information about one or more orders. 

To retrieve information, edit the URL and add one or more Click & Drop order numbers separated by semicolons. 

Example:

{{baseURL}}/{{version}}/Orders/30234;30235

And information will be retrieved in the following format:

Example:

[
{
"orderIdentifier": 30235,
"orderReference": "",
"createdOn": "2020-07-13T07:54:50",
"orderDate": "2020-07-06T09:19:44",
"trackingNumber": ""
},
{
"orderIdentifier": 30234,
"orderReference": "",
"createdOn": "2020-07-06T09:19:44",
"orderDate": "2020-07-06T09:19:44",
"printedOn": "2020-07-08T11:35:53",
"shippedOn": "2020-07-13T07:54:36",
"trackingNumber": ""
}
]

5. Troubleshooting

 Error code list:

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 - unauthorized

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.

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.