# Send orders to a fulfilment provider

> Connect a warehouse that packs and ships your store's orders, choose which orders it gets, and follow what is sent to it and what comes back.

Source: https://docs.coritan.com/organizations/commerce/fulfilment-providers/

In the dashboard:

- /dashboard/organizations/…/commerce/settings: https://www.coritan.com/dashboard/organizations

A fulfilment provider is whoever packs and ships an order. A **Webhook** provider is a warehouse, often called a 3PL, that Coritan sends each order to, signed; the 3PL posts shipments and tracking back. A **Manual** provider stands for your own team, which ships and adds tracking from the order's page. While the store has no provider, you fulfil orders by hand from their pages.

## Before you begin

- You need the Admin or Owner role to add or change providers. Tier 1 support and above can see the list and each webhook provider's recent activity.
- For a webhook provider, you need the 3PL's endpoint, an `https` address on a public host. The 3PL checks Coritan's signature on each order and signs what it posts back. [Connect a fulfilment provider](/organizations/storefront/commerce-api/#connect-a-fulfilment-provider) describes what it receives and sends.
- A store has at most 20 providers.

## Add a provider

1. In the [dashboard](https://www.coritan.com/dashboard/organizations), open the organization, then **Commerce**, then **Settings**.
2. On the **Fulfillment providers** card, select **New provider…**.
3. Choose the **Kind**: **Webhook** or **Manual**. It cannot be changed later.
4. Enter a **Name** of up to 100 characters. It shows on your order pages, and the 3PL never sees it.
5. For a webhook provider, enter the **Endpoint**, of up to 1,000 characters. Coritan posts each order to it.
6. Leave **Turned on** ticked, unless the provider should not take orders yet.
7. For a webhook provider, choose under **Sending orders**:
   - **Send orders on their own**: a placed order goes out after the wait. Turned off, you send each order from its page.
   - **Wait before sending**: the minutes to wait after an order is placed, up to 10,080, so a mistake can be put right before the 3PL starts packing. The store's own wait under **Fulfillment** is the least any provider waits.
   - **Send prices**: each item's price and the order's totals go with the order, for customs forms and packing slips.
   - **Takes returns**: returned goods go back to this 3PL. Coritan tells it about each return on its way, and it reports when the goods arrive.
8. A shipping option's own service code goes to the 3PL as it is. When this 3PL calls it something else, select **Add a service code**, enter the option's number or its code in **Shipping option or its code**, then enter **This 3PL's code**. You can map up to 200 options.
9. Select **Create provider**.

For a webhook provider, **Save these secrets now** then shows what the 3PL needs:

**Sends to**
: The endpoint Coritan posts orders to.

**Events address**
: Where the 3PL posts shipments, tracking and returns.

**Outbound secret**
: The 3PL checks it on what Coritan sends.

**Inbound secret**
: The 3PL signs what it posts back with it.

Give them to the 3PL, then select **I have saved them**.

> [!IMPORTANT]
> The secrets are shown once. If you lose them, rotate them and give the 3PL the new ones.

## Choose which orders it gets

Each stock location can name a provider in **Fulfilled by**, as [Inventory](/organizations/commerce/inventory/#add-a-stock-location) shows. For each item, Coritan picks the first of these:

1. the provider the order's shipping option names in its own **Fulfilled by**, set in [Shipping](/organizations/commerce/shipping/#add-a-shipping-option)
2. the provider of the stock location the item's stock is reserved at
3. the store's only provider that is turned on, when exactly one is
4. nobody, so you fulfil the item by hand from the order's page

The **Locations** column lists the locations that name each provider, and **Sends orders** says when orders go to it: at once, after a wait, from the order's page or by your team.

## Test it and follow what is sent

- **Send a test** in the provider's menu posts a test to the endpoint. A message says whether it accepted it, with the HTTP status it answered.
- **Recent activity…** opens the log. **Sent to it** lists the orders, cancellations, returns and tests Coritan posted, with **Waiting**, **Delivered** and **Failed** filters. **Received from it** lists what the 3PL posted back, with **Processed**, **Failed** and **Ignored** filters. **Older** loads more.
- **Last delivery** shows when the last post succeeded, or the error of the last one that failed.

A post is delivered when the endpoint answers with a 2xx status. A timeout, a failed connection, or an answer of 408, 429 or 5xx is tried again after 1, 5, 30, 120 and 480 minutes, and then fails. Any other answer fails at once, and redirects are not followed. After five failures in a row, the list marks the provider **Failing**, and your [organization webhooks](/organizations/webhooks/) receive `commerce.fulfillment.provider_failing`.

An order that did not reach its provider shows its parcel as **Needs attention** on the order's page, where **Send again** posts it once more.

## Change, turn off or delete a provider

Every action is in the menu on the provider's row.

**Edit provider…**
: Change anything but the kind, then select **Save provider**.

**Rotate secrets…**
: Type the provider's name, then select **Rotate secrets**. New secrets are shown once, and the old ones stop working at once, so the 3PL needs the new ones before it can check what Coritan sends or sign what it posts back.

**Turn off…** and **Turn on**
: While a provider is turned off, new fulfilments cannot use it and nothing is sent to it. What waits for a webhook provider goes out once it is turned on again.

**Delete provider…**
: Type the provider's name, then select **Delete provider**. What still waits to be sent to it is marked failed. The locations that named it send their orders to the only other provider turned on, or leave them to be fulfilled by hand.

> [!CAUTION]
> Rotated secrets and deleted providers cannot be brought back.

## Result

The provider is in the **Fulfillment providers** list, and its locations' orders go to it as **Sends orders** says. On an order's page, each parcel names who packs it, and its status follows what the provider reports.

## Troubleshooting

**Orders are not sent to providers on their own**
: **Send orders to webhook providers on their own** is turned off for the whole store under **Fulfillment**, so you send each order from its page. Turn it on in [Settings](/organizations/commerce/settings/#fulfillment).

The provider is marked **Failing**
: Its last five posts failed. Read the error under **Last delivery**, fix the endpoint or ask the 3PL, then select **Send a test**.

The provider cannot be deleted
: It holds fulfilments that have not shipped. Ship or cancel them first, or turn the provider off instead.

The endpoint is refused
: It must start with `https://` and point to a public host. The error under **Endpoint** gives the reason.

## Related

- [Fulfil, refund and cancel store orders](/organizations/commerce/orders/)
- [Track stock and stock locations](/organizations/commerce/inventory/)
- [Change your store's settings](/organizations/commerce/settings/)

## With the API

The providers are under `https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/fulfillment-providers`, with `rotate-secrets`, `test`, `deliveries` and `events` under each one. [Connect a fulfilment provider](/organizations/storefront/commerce-api/#connect-a-fulfilment-provider) has the payloads, the signature and the events a 3PL posts back.

```bash
curl "https://api.coritan.com/api/v1/orgs/acme/commerce/fulfillment-providers" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```