FleetConnector Spoke Documentation

Automatic Plan Management

FleetConnector Spoke automatically manages plans for you:

• • When an order is created, the plugin checks the delivery date
• • The plan for that date is looked up by its date in Spoke (all pages of your plans), so no duplicate plans are created
• • If a plan exists for that date, the stop is added to it
• • If no plan exists, a new daily plan is automatically created
• • When two orders for the same date are sent at the same time, only one plan is created
• • Plan IDs are cached to minimize API calls

• • The time slot the customer chose; without one, any time that day (default). The slot is read from Order Delivery Date, Iconic Delivery Slots, YITH Delivery Date or a delivery_time field, for example “09:00 - 12:00” or “9 AM to 12 PM”.
• • The time slot the customer chose; without one, the default window. Orders without a slot get the default window below.
• • No time window. Stops can be delivered any time that day.

Life cycle

• • Created right after the delivery is sent to Spoke.
• • Follows every change of the order (address, products, dates), also after the delivery is completed, for example when a rental is extended.
• • Removed when no product in the order needs a pickup anymore, and created again when one does.
• • Removed together with the delivery whenever the plugin removes the delivery, for example when the order is cancelled and the plugin is set to delete it then (see 2.4).
• • Left alone once the pickup itself is completed, failed or deleted in Spoke.

• • The number of days comes from the product, then from its category, then from the “Pickup after (days)” setting (default: 7).
• • The setting “Count pickup days as” chooses calendar days (default) or business days. Business days are Monday to Friday; developers can change them with the fcs_business_days filter.

• • A failed delivery or pickup sets the “Stop Failed Status” right away, with both rules.
• • A pickup stop that the dispatcher deletes in Spoke counts as cancelled and no longer holds the status back: the status is set then.

• • The order types are the stop’s activity: Delivery (delivery) and Pickup (pickup).
• • The pickup stop is added to the Spoke plan of the pickup date, with recipient external ID <order ID>-P. After a timeout, the plugin looks it up with filter[externalId] in that plan before it sends it again, so no duplicate is created.
• • A stop can’t move to another plan, and its address can’t be changed. When the pickup date or the address changes, a pickup stop that is not dispatched, started or attempted yet is deleted and created again in the right plan (with an order note). A stop that is already dispatched stays as it is, and a warning is logged once (“Linked pickup not moved (already dispatched)”); change it in Spoke if needed.
• • The data of the pickup stop starts from the delivery stop and the fcs_stop_data_before_create filter, which gets “pickup” as a third argument for the pickup stop. The plugin sends no time window itself.
• • A pickup stop that the dispatcher deletes in Spoke counts as cancelled: it no longer holds back the completed status, and it is not created again automatically. Use the order action “Update Spoke description” to send it again.
• • A pickup that the plugin removes because no product in the order needs it anymore (from version 1.1.1) also no longer holds back the completed status: when the delivery was already completed, the status is set then.
• • A failed pickup is not retried by the background queue: it is retried on the next update of the order or with the order action “Update Spoke description”.

Webhook security

• • Signature check: when a webhook signing secret is saved, a webhook without a valid spoke-signature header is rejected.
• • Verified with the Spoke API: for every stop event, the plugin fetches the stop from the Spoke API with your API key before the order is changed. A forged request can’t mark an order as delivered. This check also runs when no secret is set.

WooCommerce → Spoke Flow

Stop Data Structure

{
    "address": {
        "addressName": "Jan Jansen",
        "addressLineOne": "Keizersgracht 123",
        "city": "Amsterdam",
        "zip": "1015 CJ",
        "country": "Netherlands"
    },
    "recipient": {
        "name": "Jan Jansen",
        "phone": "+31612345678",
        "email": "jan@example.com",
        "externalId": "123"
    },
    "notes": "Order Number: 123 …",
    "activity": "delivery",
    "packageCount": 2,
    "orderInfo": {
        "sellerOrderId": "123",
        "products": ["2 x Flowers"]
    },
    "timing": {
        "earliestAttemptTime": { "hour": 9, "minute": 0 },
        "latestAttemptTime": { "hour": 12, "minute": 0 }
    }
}

Address

• • Stops are sent with a structured address (addressLineOne, addressLineTwo, city, state, zip, country, addressName). Spoke’s API doesn’t accept a single “unparsed” address line.
• • The shipping address is used, or the billing address when the order has no shipping address. The country is always sent as the country name; empty fields are left out.

Limits

• • Notes are limited to 2000 characters (Spoke’s limit). Longer notes are cut off.
• • packageCount is the number of items in the order, and at least 1.
• • timing is only sent when the order has a time window (see 2.5). weight is only sent when that setting is on.
• • For a business order the recipient name is “Company (First Last)”.

Phone number

The phone number is converted to international format with the calling code of the order’s country: the shipping country, or the billing country when the phone number came from the billing details.

• • A number that starts with + is kept as it is.
• • A 00 prefix is replaced by +.
• • North America (+1): a 10-digit number gets +1; an 11-digit number starting with 1 gets +.
• • Italy, San Marino and Vatican City: the leading 0 is kept after the country code.
• • A number that already starts with the country code (no leading 0, at least 10 digits, at least 8 digits after the code) is kept with a + in front.
• • Otherwise the leading 0 is dropped and the country code is added (0612345678 → +31612345678 for the Netherlands).

An order without a phone number is sent without a phone number; no placeholder number is used.