Send orders to a fulfilment provider

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.

The Fulfilment section of the Commerce tab holds the providers, and when placed orders go to them. Its Delivery tracking card follows shipped FedEx parcels and marks them delivered when FedEx does, whoever packed them (Track FedEx parcels).

• 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 that is not one of Coritan's own (The endpoint is refused). Your organization's own app or service on Coritan can be the endpoint too, the same ones that can receive your organization's webhooks: Coritan then sends each order through its edge, as a visitor's request arrives. The 3PL checks Coritan's signature on each order and signs what it posts back. Connect a fulfilment provider describes what it receives and sends.
• A store has at most 20 providers.
• For delivery tracking, a project in the FedEx Developer Portal with the Track API added. A provider is not needed.

1. In the dashboard, open the organization, then Commerce, then Setup, then Fulfilment.
2. On the Fulfilment 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 Fulfilment 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.

Each stock location can name a provider in Fulfilled by, as Inventory 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
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.

The Fulfilment card, above the providers, holds two settings for the whole store. You need the Admin or Owner role to change them.

Send orders to providers on their own

On by default. A placed order goes to its provider after the wait below, or after the provider's own wait if that is longer. Turned off, you send each order from its page.

Wait before sending

The least time any provider waits after an order is placed, so a mistake can still be put right: up to 10,080 minutes, which is a week. Unset, there is no wait.

Select Save changes on the card to keep them, or Discard to put them back.

Delivery tracking asks FedEx whether each shipped parcel arrived, and marks the parcel delivered when FedEx says it did. It works for any shipped parcel whose carrier is FedEx, such as FedEx or FedEx Ground, or whose tracking link is on fedex.com, whether you shipped it by hand or a provider reported it. Without it, a parcel becomes delivered only when you select Mark delivered… on the order or your provider reports the delivery.

A parcel that tracking marks delivered gets FedEx's own delivery time. Coritan then does everything that Mark delivered… does: it sends the delivered email when you turned it on, sends the commerce.fulfillment.delivered event to your webhooks, lets payouts come forward once every parcel of the order is delivered, and starts the return window (What delivered does).

You need the Admin or Owner role. Every member can read the card.

1. In the FedEx Developer Portal, create a project and add the Track API to it.
2. Copy the project's production API key and secret key.
3. In the dashboard, open the organization, then Commerce, then Setup, then Fulfilment.
4. On the Delivery tracking card, enter the FedEx API key. It is 8 to 64 letters, digits, hyphens or underscores.
5. Enter the FedEx secret key, up to 2,048 characters with no spaces. Coritan stores it encrypted and never shows it again. Later, leave the box blank to keep it, or enter a new key to replace it.
6. Select Save changes.
7. Select Test the connection. Coritan asks FedEx for a token with the keys, and about one tracking number, either a recent FedEx parcel's or a sample one. A message says whether FedEx accepted the keys. A number FedEx does not know still passes, since the token proves the keys. The button waits until you saved both keys and have no unsaved changes.
8. Turn on Track FedEx parcels, then select Save changes.

To try keys from a FedEx test project first, turn on Use FedEx's test servers. While it is on, nothing is tracked and no order is marked delivered, so turn it off before you rely on tracking.

To get the delivery email as well, turn on Email the shopper when a parcel is delivered under Emails (Turn the delivery email on or off). It is off until you do.

• Every 15 minutes, Coritan checks the store's shipped parcels with a FedEx tracking entry.
• A parcel is checked at most every 2 hours, and only for 14 days after it shipped.
• Each run asks FedEx about up to 120 tracking numbers for the store. A larger backlog takes several runs.
• Parcels of test orders are not checked, and neither are parcels whose carrier is not FedEx.
• A parcel FedEx has not delivered stays shipped, and Coritan asks again later.

The card shows Last check, Parcels checked and Marked delivered for the latest run. When FedEx refused the keys or could not be reached, the card shows The last check failed with the reason, and tracking tries again at the next run.

• 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 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.

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.

The provider is in the Fulfilment 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.

Orders are not sent to providers on their own

Send orders to providers on their own is turned off for the whole store under Fulfilment, so you send each order from its page. Turn it on in the Fulfilment card, as Choose when orders are sent shows.

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.

Test the connection says FedEx did not accept the keys

The API key or the secret key is wrong, or the project has no Track API. Copy both again from the project's production keys, paste them, select Save changes, then test again. Keys from a FedEx test project work only with Use FedEx's test servers turned on.

A FedEx parcel stays shipped after it arrived

Check that Track FedEx parcels is on and Use FedEx's test servers is off. A parcel is followed only for 14 days after it shipped, and only when its tracking entry names FedEx. Select Mark delivered… on the order for any parcel tracking will not reach.

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, without a user name or password in it. Coritan refuses a private, loopback, link-local or cloud metadata address, and its own hosts: every brand's site and the names under it, the dashboard, the API, its mail servers, its edge servers and its game servers, and every deployment's platform address on App Deployment (URL points at the platform itself). Your organization's own app or service is the exception (Send events to your own deployment). Another organization's is refused like any other Coritan address, as resolves to an address of the platform itself. The error under Endpoint gives the reason. Each post is checked again before it goes, and goes to the address that check found, so a name pointed somewhere else afterwards never receives it.

• Fulfil, refund and cancel store orders
• Track stock and stock locations
• Change your store's settings
• Write the emails your store sends

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 has the payloads, the signature and the events a 3PL posts back.

FedEx delivery tracking is the integration fedex, under https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/integrations/fedex. PUT takes enabled, test_mode, config with client_id (the FedEx API key) and the write-only secret (the FedEx secret key), and POST .../fedex/test checks the saved keys. GET .../commerce/integrations lists it with tracking, which is null before the first run and then {last_run_at, last_result, last_error, checked, delivered}. fedex receives no events. The integrations guide has the shared routes.

curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/commerce/integrations/fedex" \
  -H "Authorization: Bearer $CORITAN_TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled": true, "config": {"client_id": "'"$FEDEX_API_KEY"'"}, "secret": "'"$FEDEX_SECRET_KEY"'"}'

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