Using the REST API to create custom courier integrations

This guide explains how to connect your own courier to StoreFeeder using the REST API. You add a custom courier and shipping method in StoreFeeder, your system collects the orders and books them with your courier, and then sends the courier's label back to StoreFeeder so it prints during your normal despatch process.

How it works

StoreFeeder doesn't talk to your courier directly. Instead a system you (or your developer's) has created sits in the middle:

1. StoreFeeder assigns orders to a shipping method that belongs to your custom courier based on your shipping rules.
2. Your system fetches those orders from the StoreFeeder REST API.
3. Your system books each order with your courier and gets back a PDF label and tracking number.
4. Your system sends the label and tracking number to StoreFeeder using the assign-label API call.
5. Your warehouse picks and despatches the orders in StoreFeeder as normal, and the courier's label prints.

Before you start

You'll need the following before you begin:

Step 1: Add a custom courier integration

1. Go to Settings > Integration Manager > Your Integrations.
2. Click New Integration.
3. Choose Courier, then choose Other.
4. Enter a Profile Name. This is usually your courier's name, for example My Courier.
5. Click Add Integration.

StoreFeeder takes you straight to the new courier's settings page. Set the following, then save:

• Company identity: the company identity these parcels are sent from.
• Tracking URL template: optional. Your courier's tracking page address with {trackingNumber} where the tracking number goes, for example https://www.mycourier.com/track?id={trackingNumber}. StoreFeeder uses this to add a tracking link to despatch emails.
• API Username and API Password: leave these blank. Your own system handles the login to your courier, so StoreFeeder doesn't need these details.

Step 2: Create a shipping method for the courier

1. Go to Settings > Shipping Configuration > Shipping Methods.
2. Click New Shipping Method.
3. Select the courier you created in Step 1.
4. Select the Integrated Label or Label shipping format.
5. Enter a Shipping method name and a Shipping cost (entering £0 is fine), then click Add Shipping Method.
6. On the Edit Shipping Method page that opens, set Label Type to Customer Generated, then click Save.

Create one shipping method for each courier service you use (for example next day and 48 hour), so you can tell them apart when you fetch orders.

Finally, make sure orders land on this shipping method. Either set up a shipping rule under Settings > Shipping Configuration > Shipping Rules > Shipping Rules, or map your channel's shipping methods to it in the channel's integration settings.

Step 3: Fetch the orders for your courier

All API calls in this guide go to https://rest.storefeeder.com. Your system fetches orders using the get orders API call, filtered to your custom courier's shipping method.

1. Call GET /shipping-methods and note the ShippingMethodID of the shipping method you created in Step 2.
2. Call GET /orders filtered by that ID, for example:
   GET /orders?ShippingMethodID=123&OrderStatus=CompleteReadyToPick&Page=1&PageSize=100

Each order in the response includes the delivery address, order lines, weight and number of packages: everything your system needs to book the parcel with your courier. Results come back up to 100 at a time; use Page to work through the rest.

Step 4: Send the courier's label to StoreFeeder

Once your courier has returned a label, your system sends it to StoreFeeder with the assign-label API call:

PUT /orders/{orderNumber}/assign-label

For example:

{ "CarrierName": "My Courier", "TrackingNumber": "MC123456789GB", "Label": "JVBERi0xLjQK..." }

A successful call returns 200 OK and StoreFeeder saves the label against the order, ready for despatch. Sending a label again for the same order replaces the previous label, carrier name and tracking number, so always include the tracking number when you re-send.

To send up to 50 labels in one request, use PUT /orders/bulk-assign-label with a list of the same fields plus OrderNumber for each. If you include the same order more than once, StoreFeeder merges its labels into one PDF. The response tells you which orders succeeded and gives the error for any that didn't.

The full request and response details for both calls are in the REST API documentation.

Step 5: Despatch as normal and print the courier's label

Your warehouse doesn't need to do anything different. Pick and despatch these orders the same way you do all other orders.

When the orders are despatched, StoreFeeder prints the label your courier supplied instead of creating one. The carrier name and tracking number you sent stay on the order and are passed to your sales channel with the despatch update. If you set a Tracking URL template in Step 1, the tracking link is included in despatch emails too.

Troubleshooting

"Label not found. Please assign a label via our Rest API" prints instead of a label
The order was despatched before your system sent its label. Send the label with the assign-label call, then reprint it using Print Despatched Labels.

"Order must have Shipping Method from custom courier to assign label"
The order is on a shipping method that doesn't belong to your Other courier. Move the order to your custom courier's shipping method, then send the label again.

"Order must have a Shipping Method with Label Type of Customer Generated to assign label"
The shipping method's Label Type isn't set to Customer Generated, or its format isn't Integrated Label. Fix it as described in Step 2, then send the label again.

"Order must be in Complete Ready To Pick, Assigned or Despatched status to assign label"
Labels can only be added to orders in one of those statuses. Check the order isn't on hold, awaiting payment or cancelled.

"Label is not a PDF" or "Label string is not in a Base64 format"
StoreFeeder only accepts PDF labels, sent as a base64 string. ZPL and image labels aren't supported, so ask your courier for a PDF label instead.

"Order does not exist"
Check you're sending StoreFeeder's OrderNumber, not the channel's order reference, and that your API key belongs to the right StoreFeeder account.

"You can send a maximum of 50 label assignments in one request."
Split your bulk-assign-label request into batches of 50 or fewer.

"Labels have already been generated for this order" when using Pre-generate Labels
This is expected: the order already has its label from your courier. Despatch it as normal.

Related articles

• StoreFeeder REST API Overview
• Getting a StoreFeeder API key
• How to self-integrate a sales channel using the StoreFeeder REST API
• How to create shipping rules