Circuit Orders API

openapi: 3.2.0
info:
  title: Spoke Connect Orders API
  description: 'This is the documentation of the Spoke Connect API HTTP endpoints. The Connect

    API is how a retailer creates, tracks, and hands off its deliveries in Spoke

    programmatically. # Introduction


    The Spoke Connect API is an HTTP API that lets you operate on your orders

    programmatically. Use it to create, edit, delete, list, and retrieve orders,

    submit them to a courier and withdraw them before they ship, and download

    printable PDF labels. Read-only endpoints expose the couriers and pickup

    locations your orders reference. Spoke offers no programming SDKs for the Connect API. Call the endpoints

    documented on this page directly, or generate a client from the

    OpenAPI spec. For worked examples of the flows a retailer integration needs, see the

    Usage Examples. # Using the API


    ## Address


    The base address for this version of the API, to be used before every endpoint

    listed here, is:


    ```

    https://api.spoke.com/connect/v1

    ```


    Notice the `https://` prefix. The Connect API will **not** accept plain HTTP

    requests. ## Your first request


    Every request must be authenticated with an API key. The following request

    lists your orders:


    ```bash

    curl "https://api.spoke.com/connect/v1/orders" \

    -H "Authorization: Bearer "

    ```


    The response contains an `orders` array, plus a `nextPageToken` cursor to pass

    as `pageToken` when there are more results to fetch. ## Authentication


    Every Connect API request must be authenticated with an API key. ### Creating API keys


    API keys are created and expired from the **Integrations** page in your Connect

    settings, by retailer admins. You can have up to 5 active keys at a time. Expired keys don''t count towards the limit. Treat your keys as secrets: don''t embed them in client-side code, and expire

    any key you suspect has leaked. ### Using your key


    Pass the key in the `Authorization` header. Both the `Bearer` and `Basic`

    schemes are accepted:


    ```

    Authorization: Bearer

    ```


    ```

    Authorization: Basic :)>

    ```


    For `Basic`, use the API key as the username and leave the password empty. `curl` builds the encoded header for you with `-u ":"`:


    ```bash

    curl "https://api.spoke.com/connect/v1/orders" -u ":"

    ```


    ### Authentication errors


    Requests with a missing, invalid, or expired key are rejected with a

    `401 Unauthorized` response. ## On resource types


    Every response from the Connect API is a JSON object, and every request that

    carries a body must send it as JSON with the `Content-Type: application/json`

    header. The API exposes four resource types:


    | Resource | What it is | Where |

    | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |

    | `Order` | A package, or set of packages, you are sending to a recipient through a courier. Everything else in the API exists to describe or act on an order. | Read and write, `/orders` |

    | `Courier` | A courier your retailer account is connected to, and that you can submit orders to. | Read-only, `/couriers` |

    | `PickupLocation` | One of your own locations a courier can collect from, referenced by an order''s `deliveryInstructions.handOffInfo.pickupLocationId`. | Read-only, `/pickupLocations` |

    | `OrderShippingLabels` | A short-lived signed link to an order''s printable labels, rendered as a single PDF. | Read-only, `/orders/{id}/shippingLabels` |


    Couriers and pickup locations are managed in the Spoke Connect app, not through

    this API. The API reads them so you can reference them by id when you create

    and submit orders. What every field on these resources means is documented on the

    Models pages. ## On resource IDs


    Every resource in the Connect API has a unique id that Spoke generates.'
  version: v1
servers:
- url: https://api.spoke.com/connect/v1
security:
- BearerAuth: []
- BasicAuth: []
tags:


# --- truncated at 32 KB (199 KB total) ---
# Full source: https://artifacts.apis.io/getcircuit-com/openapi/getcircuit-com-orders-api-openapi.yml