# Stores (API v1, deprecated)

Deprecated: API v1 keeps working for existing integrations but gets no new features. New integrations should use API v2 (https://public-api.dapi.digital/docs/guides/quickstart.md).

One store per storefront you run, so quotes and orders are kept apart per storefront.

## Endpoints

-   [GET `/v1/stores`](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_listStores)
-   [POST `/v1/stores`](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_createStore)
-   [GET `/v1/stores/{storeId}`](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_getStore)
-   [PATCH `/v1/stores/{storeId}`](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_updateStore)
-   [DELETE `/v1/stores/{storeId}`](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_archiveStore)

## The store object

### Attributes

-   `id` (string): Identifier for this store. Pass it as `store_id` on quotes and orders.
-   `name` (string): The name you gave this storefront.
-   `external_reference` (object, optional): Your own identifier for this storefront, or `null` if you did not set one.
-   `archived` (boolean): Whether this store is archived. An archived store keeps its history but refuses new quotes and orders.
-   `created_at` (timestamp): ISO 8601 timestamp of when this store was created.

**The store object**

```json
{
  "id": "str_9f2c4a7b13d84e0fa6c5b8e21d47a903",
  "name": "Clicker Shop UK",
  "external_reference": "shop_uk_001",
  "archived": false,
  "created_at": "2026-09-02T12:00:00.000Z"
}
```

## List your stores

GET `/v1/stores`

- **Credentials**: An API key with the `PRICING` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_listStores`

Returns your stores, newest first. Archived stores are excluded unless you pass `include_archived=true`.

### Query parameters

-   `page` (number): 1-based page index.
    
    Range at least 1. Defaults to 1.
    
-   `page_size` (number): Number of stores per page (max 100).
    
    Range 1 to 100. Defaults to 20.
    
-   `include_archived` (boolean): Include archived stores in the results. Defaults to `false`, so closed storefronts stay out of the way.
    
    Defaults to false.
    

### Returns 200 OK

Paginated list of stores.

Response attributes (V1ListStoresResponseDto):

-   `items` (array of V1StoreResponseDto): Stores on this page, newest first.
    
    Described in [the store object](https://public-api.dapi.digital/docs/reference/v1-stores#v1_store_object).
    
-   `page` (number): Page number returned.
    
    Range at least 1.
    
-   `page_size` (number): Number of items per page.
    
    Range 1 to 100.
    
-   `total` (number): Total number of stores matching the query, across all pages.
    
    Range at least 0.
    

### Responses

-   `200`: Paginated list of stores.
-   `400`: `page` or `page_size` is outside the allowed range.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use store endpoints.
-   `429`: Rate limit exceeded.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/stores" \
  -H "x-api-key: $DAPI_API_KEY"
```

**Response 200**

```json
{
  "items": [
    {
      "id": "str_9f2c4a7b13d84e0fa6c5b8e21d47a903",
      "name": "Clicker Shop UK",
      "external_reference": "shop_uk_001",
      "archived": false,
      "created_at": "2026-09-02T12:00:00.000Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 3
}
```

## Create a store

POST `/v1/stores`

- **Credentials**: An API key with the `PRICING` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_createStore`

Creates a store representing one of your storefronts.

A store keeps one storefront's quotes and orders bookkept apart from the others on your account. It is not an authentication boundary: your API key still reaches every store you own.

> **Once your account has at least one store, `store_id` becomes required** when creating quotes and orders. This stops a storefront from silently omitting it and mixing its records in with the rest.

### Request body

-   `name` (string, required): Human-readable name for this storefront. Shown only to you.
-   `external_reference` (string): Your own identifier for this storefront, so you can reconcile without keeping a mapping table. Opaque to us and never interpreted. Must be unique across your live stores.

### Returns 201 Created

Store created. Returns [the store object](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_store_object).

### Responses

-   `201`: Store created.
-   `400`: The request could not be validated.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use store endpoints.
-   `409`: Another live store already uses this `external_reference`.
-   `429`: Rate limit exceeded.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl -X POST "https://public-api.dapi.digital/v1/stores" \
  -H "x-api-key: $DAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clicker Shop UK",
  "external_reference": "shop_uk_001"
}'
```

## Get one store

GET `/v1/stores/{storeId}`

- **Credentials**: An API key with the `PRICING` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_getStore`

Returns the store matching the given id, archived or not.

### Path parameters

-   `storeId` (string, required): The store id returned when it was created.

### Returns 200 OK

The requested store. Returns [the store object](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_store_object).

### Responses

-   `200`: The requested store.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use store endpoints.
-   `404`: No store with this id exists for your account.
-   `429`: Rate limit exceeded.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/stores/str_9f2c4a7b13d84e0fa6c5b8e21d47a903" \
  -H "x-api-key: $DAPI_API_KEY"
```

## Update a store

PATCH `/v1/stores/{storeId}`

- **Credentials**: An API key with the `PRICING` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_updateStore`

Updates a store's name or external reference. Omitted fields are left unchanged; pass `external_reference: null` to clear it.

### Path parameters

-   `storeId` (string, required): The store to update.

### Request body

-   `name` (string): New name for this storefront.
-   `external_reference` (object): New external reference. Pass `null` to clear it. Omit to leave it unchanged.

### Returns 200 OK

The updated store. Returns [the store object](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_store_object).

### Responses

-   `200`: The updated store.
-   `400`: No updatable field was provided, or the body failed validation.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use store endpoints.
-   `404`: No store with this id exists for your account.
-   `409`: Another live store already uses this `external_reference`.
-   `429`: Rate limit exceeded.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl -X PATCH "https://public-api.dapi.digital/v1/stores/str_9f2c4a7b13d84e0fa6c5b8e21d47a903" \
  -H "x-api-key: $DAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clicker Shop UK & IE",
  "external_reference": "shop_uk_002"
}'
```

## Archive a store

DELETE `/v1/stores/{storeId}`

- **Credentials**: An API key with the `PRICING` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_archiveStore`

Archives a store. Its quotes and orders are kept and stay readable, but the store refuses new ones.

Stores are never hard-deleted, because orders reference them and that history has to survive a storefront closing. Archiving twice is safe and leaves the original archive date intact.

### Path parameters

-   `storeId` (string, required): The store to archive.

### Returns 200 OK

The archived store. Returns [the store object](https://public-api.dapi.digital/docs/v1/reference/stores.md#v1_store_object).

### Responses

-   `200`: The archived store.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use store endpoints.
-   `404`: No store with this id exists for your account.
-   `429`: Rate limit exceeded.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl -X DELETE "https://public-api.dapi.digital/v1/stores/str_9f2c4a7b13d84e0fa6c5b8e21d47a903" \
  -H "x-api-key: $DAPI_API_KEY"
```

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/v1/reference/stores. Index of every page: https://public-api.dapi.digital/docs/llms.txt.
