> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zones

> Connect Serval to Zones to create purchase orders, track order status, and read the standard and non-standard product catalogs on demand.

## About Zones

Zones is an IT solutions and hardware reseller. Serval connects to the Zones API to place and track orders and to read product catalogs, calling Zones' REST API on your behalf whenever a Serval workflow runs.

**Authentication:** A Zones API **subscription key** (sent as the `Ocp-Apim-Subscription-Key` header) plus **OAuth 2.0 client credentials** (Client ID, Client Secret, and a Scope). Serval exchanges the client credentials for a short-lived bearer token at Zones' token endpoint and sends both the bearer token and the subscription key on every request.

**Environment:** This integration targets the Zones test environment (`apitest.zones.com`).

**Data sync:** On-demand only - there is no background sync or scheduled ingestion. Serval reads from and writes to Zones at the moment a Serval workflow runs.

<Note>
  The Zones **Advance Shipment Notification (ASN)** service is a separate, event-driven product: Zones *pushes* shipment updates to a URL you register, rather than exposing endpoints Serval calls. It is not part of this integration, which covers the Orders and Product Catalog REST APIs.
</Note>

## What the Zones integration enables

| Capability                  | Description                                                                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Create purchase orders      | `POST /orders/v1/purchase-order` submits a new order to Zones, returning the created order reference.                                        |
| Track order status          | `GET /orders/v1/purchase-order/{zonesOrderNumber}` retrieves full details and tracking information for an existing order.                    |
| Read the product catalog    | `GET /catalog/v1/standards` and `GET /catalog/v1/non-standards` return the standard and non-standard product catalogs.                       |
| Call any Zones API endpoint | A generic, typed API request action exposes every endpoint above with request/response types generated from the Zones OpenAPI specification. |

## Get your credentials

Serval needs two things from the [Zones developer portal](https://developer.zones.com): a **subscription key** and an **OAuth client** (Client ID, Client Secret, and Scope).

<Steps>
  <Step title="Sign in to the Zones developer portal">
    Go to [developer.zones.com](https://developer.zones.com) and sign in with your Zones developer account.
  </Step>

  <Step title="Copy your subscription key">
    Open your **Subscriptions** (or **Profile**) page and copy the subscription key for the products you need (Orders API and Product Catalog). This value is sent as the `Ocp-Apim-Subscription-Key` header on every request.

    <Warning>
      Treat the subscription key like a password. If it's ever exposed, regenerate it from the portal and update the Serval connection.
    </Warning>
  </Step>

  <Step title="Find your client credentials">
    On your **Profile** page, open the **Environment Secrets** section. Copy the **Client ID**, **Client Secret**, and the **Scope** (the app name used as the token scope).

    <Tip>
      The Scope is the application name shown alongside the client credentials - not a permission string. Copy it exactly as shown.
    </Tip>
  </Step>
</Steps>

## Connect in Serval

All four fields are required. The form flags any required field left blank, and an incomplete configuration that reaches Serval's backend is rejected with a message beginning "Invalid Zones configuration" (for example, "subscription key is required" or "client ID is required").

<Steps>
  <Step title="Enter the Subscription Key">
    Your Zones API subscription key from the developer portal's Subscriptions page. Stored encrypted. When editing the connection later, it appears obfuscated - leave it unchanged to keep the stored value.
  </Step>

  <Step title="Enter the Client ID">
    The OAuth client ID from the Environment Secrets section of your Zones profile.
  </Step>

  <Step title="Enter the Client Secret">
    The OAuth client secret from the same section. Stored encrypted; obfuscated on the edit form - leave it unchanged to keep the stored value.
  </Step>

  <Step title="Enter the Scope">
    The app name used as the token scope, from the Environment Secrets section.
  </Step>
</Steps>

## Verifying the connection

After saving, Serval runs these health checks:

* **Test Zones Connection** - performs the full client-credentials token exchange, then fetches the standard catalog to confirm both the subscription key and token are valid. On success: "Successfully authenticated with Zones". On failure: "Unable to connect to Zones. Please verify your Subscription Key, Client ID, Client Secret, and Scope are valid."
* **List Zones Standard Catalog** - confirms the Product Catalog API is reachable by fetching the standard catalog.
* **List Zones Non-Standard Catalog** - confirms the Product Catalog API is reachable by fetching the non-standard catalog.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Every request needs both credentials">
    Zones requires two credentials on each Orders/Catalog call: the `Ocp-Apim-Subscription-Key` header and an `Authorization: Bearer` token. Serval handles both automatically - it exchanges your Client ID, Client Secret, and Scope for a bearer token and attaches the subscription key. A `401` usually means the bearer token or client credentials are wrong; a `403` typically means the subscription key lacks access to the product being called.
  </Accordion>

  <Accordion title="Scope is an app name, not a permission">
    The Scope field is the application name from the portal's Environment Secrets, sent verbatim in the token request. If it doesn't match what the portal shows, the token exchange fails and requests are rejected. Update it in Serval whenever it changes in the portal.
  </Accordion>

  <Accordion title="Bearer tokens are short-lived">
    Zones access tokens expire about an hour after they're issued. Serval requests a fresh token as needed, so no action is required - but a token endpoint outage surfaces as an authentication failure even when your credentials are correct.
  </Accordion>

  <Accordion title="Test environment">
    This integration targets `apitest.zones.com`. Make sure the subscription key and client credentials you enter belong to the same environment.
  </Accordion>

  <Accordion title="Request paths include the product prefix">
    For teams building custom automations through the generic API request action, paths already include the product prefix - for example `/orders/v1/purchase-order` and `/catalog/v1/standards`. Do not add `https://` or the host; Serval routes requests to Zones automatically.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Zones integration.