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

# Check Period Overlap

> Ask whether any sold product period in your organization already covers a date range, before you create one

[← Sold Products API](/api-reference/sold-products/overview)

Ask whether any sold product period in your organization already covers a given date range. Call it before creating a period so you can warn the user instead of silently double-counting the same sales across two overlapping periods.

<Note>
  **One boolean, no detail.** The response tells you *whether* something overlaps, not *what*. If you need to show the user which period is in the way, follow up with the [period list](/api-reference/sold-products/list-periods) for the product in question.
</Note>

## Request

### Headers

<ParamField header="x-organization-id" type="string" required>
  UUID of the organization to check. The search covers every sold product in this organization — not just one product — so a period on any product can produce an overlap.

  **Format:** UUID
</ParamField>

<ParamField header="x-api-key" type="string">
  Your API key.
</ParamField>

### Query Parameters

<ParamField query="start_date" type="string" required>
  First day of the range you want to check.

  **Format:** `YYYY-MM-DD`
</ParamField>

<ParamField query="end_date" type="string" required>
  Last day of the range you want to check.

  **Format:** `YYYY-MM-DD`
</ParamField>

<Warning>
  **Both bounds are inclusive, on both sides.** A period that ends exactly on your `start_date` — or begins exactly on your `end_date` — counts as an overlap. Touching ranges are overlapping ranges here.

  So checking `2026-04-01 → 2026-06-30` against an existing period of `2026-01-01 → 2026-04-01` returns `true`, because the two share 1 April. If your model treats consecutive periods as adjacent rather than overlapping, start the new range on the day *after* the previous one ends.
</Warning>

## Response

<ResponseField name="has_overlap" type="boolean">
  `true` when at least one sold product period in the organization intersects the range, `false` when none does.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/sold-products/periods/check-overlap?start_date=2026-04-01&end_date=2026-06-30" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-organization-id: YOUR_ORGANIZATION_ID"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  HEADERS = {
      "x-api-key": "YOUR_API_KEY",
      "x-organization-id": "YOUR_ORGANIZATION_ID",
  }

  result = requests.get(
      "https://api.dcycle.io/v1/sold-products/periods/check-overlap",
      headers=HEADERS,
      params={"start_date": "2026-04-01", "end_date": "2026-06-30"},
      timeout=30,
  ).json()

  if result["has_overlap"]:
      raise ValueError("that range is already covered by an existing period")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({
    start_date: "2026-04-01",
    end_date: "2026-06-30",
  });
  const response = await fetch(
    `https://api.dcycle.io/v1/sold-products/periods/check-overlap?${params}`,
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
    },
  );
  const { has_overlap: hasOverlap } = await response.json();
  ```
</CodeGroup>

### Successful Response

Returns `200 OK`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "has_overlap": true
}
```

## Common Errors

### 422 Unprocessable Entity

**Cause:** `start_date` or `end_date` is missing. Both are required — there is no "check from here onwards" mode.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "end_date"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

**Cause:** A date is not in `YYYY-MM-DD` form.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "start_date"],
      "msg": "invalid date format",
      "type": "value_error.date"
    }
  ]
}
```

## Use Cases

### Validate before you create, not after

Sold product periods are how sales are attributed to a reporting window. Two periods covering the same days mean the same sales are counted twice, and nothing downstream flags it — the totals simply come out too high. Checking first turns that into a message the user can act on.

### Guide a user to the next free range

When `has_overlap` is `true`, the simplest recovery is to move the start date forward a day and check again. Because the bounds are inclusive, a range starting the day after an existing period ends is guaranteed not to overlap it.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Periods" icon="calendar" href="/api-reference/sold-products/list-periods">
    The periods that already exist, and their dates
  </Card>

  <Card title="List Sold Products" icon="list" href="/api-reference/sold-products/list">
    Every sold product in the organization
  </Card>

  <Card title="Sold Products API" icon="box" href="/api-reference/sold-products/overview">
    Everything the Sold Products API covers
  </Card>
</CardGroup>