Send orders to a supplier's API

Send orders straight into a supplier's own system with an API Call. You define the request, Dropday fills it with the order data and reads the supplier's response to see whether the order was accepted.

Dropday has no ready-made integrations with specific supplier systems. An API Call works with any system that can receive orders through a JSON API, so you need the supplier's API documentation: the address to send orders to, how the API checks your access (for example an API key) and the message it expects. You also need a supplier in Dropday.

An API Call sends orders from Dropday to your supplier. It isn't the Dropday API, which works the other way round: your webshop or own system uses it to send orders to Dropday.

Add an API call

On the supplier's page, click Add action and choose API Call.
Choose the HTTP method the supplier's API expects (POST, GET or PUT) and enter its address in Host. Dropday accepts both http and https addresses, so whether the order is encrypted on its way to the supplier depends on the address you enter.
In Headers, add the headers the supplier's API needs, one per line, for example Authorization: Bearer YOUR_API_KEY.
In Body, write the JSON the supplier's API expects, with placeholders for the order data (see below). Dropday has no fixed structure for it: the body must result in valid JSON (an object or an array), or the call fails and nothing is sent. Include every order detail the supplier needs yourself, including extra fields such as personalisation.
If the supplier's API answers with a value that confirms the order, enter the key and value in its JSON response that mean success. You can also save a message from the response in the order line log.
Test the call, then save.

Put order data in the request

Placeholders are written in double braces, such as {{ order.reference }}, and work the same way in Host, Headers and Body.

These order placeholders are available:

the order: order.external_id, order.reference, order.created_at and order.comment;
the customer: order.company_name, order.first_name, order.last_name, order.email and order.phone;
shipping: order.shipping_name, order.shipping_description, order.shipping_cost, order.shipping_note and order.shipping_delivery_date;
the address: order.address1, order.address2, order.city, order.postcode, order.country, order.country_iso and order.state;
your own order fields: order.custom.<name>, with the name of the field in place of <name>.

In a call that runs once per order, the order line fields are available inside a loop over the order lines, between {% for line in orderLines %} and {% endfor %}: line.quantity, line.name, line.reference, line.ean13, line.price, line.purchase_price, line.brand, line.category, line.image_url, line.weight, line.height, line.width, line.length, and your own line fields as line.custom.<name>.

Send a call per order or per product

An API call runs once per order or once per product, and you can give it a condition: when the condition isn't met, Dropday skips the call and logs it as skipped.

Call once per order: one call carries all order lines of this supplier. Write the lines in a loop, as in the first example below.
Call once per product in order: the call runs once for each order line, so you don't need a loop. The current line is available as line, for example {{ line.reference }} and {{ line.quantity }}, and also line.id, line.external_id and line.supplier.

Example: send an order with its order lines

This example is illustrative and not directly usable: the address and the field names in the body are made up. Take the method, address, headers and fields from your supplier's API documentation.

The call sends one order to the supplier: the order reference, the shipping address, the customer's note and a list of the order lines. Choose Call once per order, set the method to POST and Host to the supplier's order address, here https://api.example-supplier.com/v1/orders. In Headers, replace YOUR_API_KEY with the key your supplier gave you:

Authorization: Bearer YOUR_API_KEY

In Body, Dropday replaces each placeholder with the order's data when it sends the call. Between {% for line in orderLines %} and {% endfor %}, it repeats one object for each order line of this supplier, here with the reference as the supplier's SKU and the quantity:

{
  "order_reference": "{{ order.reference }}",
  "ship_to": {
    "name": "{{ order.first_name }} {{ order.last_name }}",
    "company": "{{ order.company_name }}",
    "street": "{{ order.address1 }}",
    "postcode": "{{ order.postcode }}",
    "city": "{{ order.city }}",
    "country": "{{ order.country_iso }}"
  },
  "note": "{{ order.comment }}",
  "lines": [
    {% for line in orderLines %}
    { "sku": "{{ line.reference }}", "quantity": {{ line.quantity }} }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}

{% if not loop.last %},{% endif %} puts a comma after every order line except the last, so the list stays valid JSON for an order with one line or with several. When you add a line field from the Order Lines menu, the menu inserts this part for you. Besides loop.last, the menu also offers loop.index and loop.index0; there is no join filter.

For an order with two order lines for this supplier, the supplier receives the order details and a lines list with two objects. Test the call from its settings. If you set the success key and value, Dropday checks them in the supplier's response; a call that fails is logged on the order lines.

Example: get a token first, then send the order

Some APIs need a token before they accept an order. Add two API calls to the supplier: they run in the order of the supplier's action list, and you change that order by dragging an action.

This example is illustrative and not directly usable: the addresses and field names are made up.

The first call asks for the token. Set the method to POST, Host to https://api.example-supplier.com/v1/auth/token, and Body to the login your supplier gave you, replacing YOUR_USERNAME and YOUR_PASSWORD:

{ "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" }

The supplier answers with JSON such as {"token": "…"}. The second call reads that answer as response, so its header uses the token like this:

Authorization: Bearer {{ response.token }}

Give the second call the order address and the body from the first example. A nested value in the response, such as id inside data, is written {{ response.data.id }}, and the Previous Response menu lists the keys Dropday has seen in recent responses for this supplier.

Result

Once a rule assigns order lines to this supplier, Dropday sends the API call when the order comes in, unless the supplier holds orders for review. If the supplier has other active delivery methods, such as Send Email, they run too.

A call that fails is logged on the order lines. The send to the supplier only counts as failed when all its delivery methods failed.

Good to know

API Call doesn't place test orders at the supplier, so a test order doesn't check this delivery. Testing the call from its settings checks that single call.
Dropday calls the supplier's API only once an order exists, to send it. It doesn't look up stock or delivery dates in the supplier's API before an order is placed.

Next, create a rule that assigns order lines to this supplier, if you haven't yet.