# Karla API (1.0.0)

The Karla API (version 1) provides programmatic access to the Karla platform. The API is organized around RESTful HTTP endpoints.

# Getting started

To get started with the Karla API, you'll need to:

1. **Register an organization and shop** - [Sign up for a Karla account](https://portal.gokarla.io), create or join an organization and set up your first shop. Remember your `shop slug`, it will be required in all API URIs.
2. **Obtain API credentials** - Generate an API key in the Settings section.
3. **Set up authentication** - Use HTTP Basic Auth with your API credentials.
4. **Make your first request** - Test the connection with a simple API call.
5. **Explore the endpoints** - Use this documentation to understand available operations.

## Quick Start Example

Here's a simple example to verify your API access:

```bash
curl https://api.gokarla.io/v1/shops/your-shop-slug \
  -u your-username:your-private-api-key
```

## Base URL

All API requests should be made to:

```text
https://api.gokarla.io/v1/
```

## Request Format

- **Content-Type**: `application/json`
- **Accept**: `application/json`
- **Encoding**: UTF-8

## Response Format

All responses are returned in JSON format. Successful responses will have HTTP status codes in the 2xx range.

```json
{
  "data": "...",
  "metadata": "..."
}
```

# Authentication

The Karla API uses HTTP Basic Authentication to secure endpoints. Your username is the one you assigned to the API key (if not given, it defaults to the shop slug), and your password is the generated API key.

## How It Works

HTTP Basic Authentication requires you to send credentials in the `Authorization` header with each request:

```text
Authorization: Basic <base64-encoded-credentials>
```

## Creating the Authorization Header

1. **Combine your credentials**: Join your username and API key with a colon

   ```text
   username:api-key
   ```

2. **Base64 encode**: Convert the combined string to Base64

   ```javascript
   // JavaScript example
   const credentials = btoa("your-username:your-api-key");
   const authHeader = `Basic ${credentials}`;
   ```

   ```python
   # Python example
   import base64
   credentials = base64.b64encode(b'your-username:your-api-key').decode('utf-8')
   auth_header = f'Basic {credentials}'
   ```

3. **Include in requests**: Add the header to your API calls

   ```javascript
   // JavaScript/Fetch example
   fetch("https://api.gokarla.io/v1/shops/your-shop-slug", {
     headers: {
       Authorization: `Basic ${credentials}`,
       "Content-Type": "application/json",
     },
   });
   ```

   ```python
   # Python/Requests example
   import requests
   response = requests.get(
     'https://api.gokarla.io/v1/shops/your-shop-slug',
     auth=('your-username', 'your-api-key')
   )
   ```

## Using cURL

With cURL, you can use the `-u` flag which automatically handles the Base64 encoding:

```bash
curl https://api.gokarla.io/v1/shops/your-shop-slug \
  -u your-username:your-api-key
```

## API Key Permissions

API keys can have different permission levels that control access to resources:

| Role     | Description                             | Access Level                           |
| -------- | --------------------------------------- | -------------------------------------- |
| `viewer` | Read-only access to resources           | Can view orders, shipments, and data   |
| `editor` | Read and write access to most resources | Can create/update orders and shipments |
| `admin`  | Full access to all shop resources       | Can manage all shop settings and data  |

## Obtaining API Keys

1. Log in to your [Karla Dashboard](https://portal.gokarla.io)
2. Navigate to **Settings** → **API Keys**
3. Select the appropriate permission level for your use case
4. Click **Create API Key**
5. Copy and securely store your credentials:
   - **Username**: Your merchant identifier
   - **API Key**: Your secret key (shown only once!)

## Error Responses

Authentication errors return specific error codes:

| Status Code | Error Key                 | Description                                     |
| ----------- | ------------------------- | ----------------------------------------------- |
| `400`       | `invalid_merchant_or_key` | Missing or malformed authentication credentials |
| `401`       | `invalid_merchant_or_key` | Invalid username or API key                     |
| `403`       | `insufficient_rights`     | Valid credentials but insufficient permissions  |

## Security Best Practices

1. **Store credentials securely**

   - Use environment variables or secure key management systems
   - Never hardcode credentials in your source code
   - Never expose credentials in client-side applications

2. **Implement proper error handling**

   - Handle authentication failures gracefully
   - Don't expose credential details in error messages
   - Implement retry logic with exponential backoff

3. **Maintain credential hygiene**
   - Use HTTPS for all API requests (HTTP redirects automatically)
   - Rotate API keys regularly
   - Revoke unused or compromised keys immediately
   - Use the minimum required permission level

# Errors

The Karla API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

- Codes in the `2xx` range indicate success
- Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an order doesn't exist, etc.)
- Codes in the `5xx` range indicate an error with Karla's servers

## Error Response Format

All error responses follow a consistent structure:

```json
{
  "key": "shop_not_found",
  "message": "Unable to find shop",
  "type": "invalid_request_error",
  "errors": []
}
```

## Error Object Properties

| Property  | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `key`     | string | A unique error code identifying the specific error. See below for all possible values. |
| `message` | string | A human-readable message providing more details about the error.                       |
| `type`    | string | The type of error returned. Either `api_error` or `invalid_request_error`.             |
| `errors`  | array  | For validation errors (422), contains detailed field-level error information.          |

## Possible Error Keys

The API returns specific error keys that help identify the exact issue:

### Client Errors (4xx)

| Error Key                         | Description                                                      | HTTP Status |
| --------------------------------- | ---------------------------------------------------------------- | ----------- |
| `a_b_test_not_found`              | The requested A/B test was not found                             | 404         |
| `a_b_test_overlap`                | An A/B test with the same segment and time period already exists | 409         |
| `announcement_exists`             | An announcement with that ID already exists                      | 409         |
| `announcement_not_found`          | The requested announcement was not found                         | 404         |
| `campaign_active_segment_exists`  | An active campaign for the same segment already exists           | 409         |
| `campaign_exists`                 | A campaign with that ID already exists                           | 409         |
| `campaign_not_found`              | The requested campaign was not found                             | 404         |
| `campaign_product_not_found`      | The requested campaign product was not found                     | 404         |
| `campaign_type_invalid`           | Invalid campaign type provided                                   | 422         |
| `carrier_reference_invalid`       | Invalid carrier reference provided                               | 422         |
| `deal_not_found`                  | The requested deal was not found                                 | 404         |
| `discount_exists`                 | A discount with that ID already exists                           | 409         |
| `discount_not_found`              | The requested discount was not found                             | 404         |
| `image_media_unsupported`         | Uploaded image format is not supported                           | 415         |
| `invalid_payload`                 | Request validation error (check `errors` array for details)      | 422         |
| `klaviyo_key_missing_permissions` | Klaviyo API key lacks required permissions                       | 400         |
| `klaviyo_key_not_found`           | Klaviyo key not configured for this shop                         | 404         |
| `order_exists`                    | An order with that ID already exists                             | 409         |
| `order_not_found`                 | The requested order was not found                                | 404         |
| `org_exists`                      | An organization with that ID already exists                      | 409         |
| `org_not_found`                   | The requested organization was not found                         | 404         |
| `permission_denied`               | User doesn't have permission for this operation                  | 403         |
| `shipment_exists`                 | A shipment with that ID already exists                           | 409         |
| `shipment_not_found`              | The requested shipment was not found                             | 404         |
| `shop_exists`                     | A shop with that ID already exists                               | 409         |
| `shop_fixtures_not_found`         | Shop fixtures need to be created first                           | 404         |
| `shop_not_found`                  | The requested shop was not found                                 | 404         |
| `shop_settings_not_found`         | Shop settings were not found                                     | 404         |
| `user_exists`                     | A user with that email already exists                            | 409         |
| `user_not_found`                  | The requested user was not found                                 | 404         |
| `webhook_exists`                  | A webhook with that configuration already exists                 | 409         |
| `webhook_not_found`               | The requested webhook was not found                              | 404         |
| `zip_code_invalid`                | Invalid zip code provided                                        | 422         |

#### Server Errors (5xx)

| Error Key                 | Description                                        | HTTP Status |
| ------------------------- | -------------------------------------------------- | ----------- |
| `bad_gateway`             | Third-party service returned an unexpected error   | 502         |
| `service_not_implemented` | The requested functionality is not yet implemented | 501         |
| `unexpected`              | An unexpected error occurred on Karla's servers    | 500         |

## Validation Errors (422)

When a request fails validation, the API returns a 422 status code with additional details in the `errors` array:

```json
{
  "key": "invalid_payload",
  "message": "Validation error",
  "type": "invalid_request_error",
  "errors": [
    {
      "loc": ["body", "email"],
      "msg": "field required",
      "type": "missing"
    }
  ]
}
```

Each validation error includes:

- `loc`: The location of the error (e.g., `["body", "email"]` for a missing email field in the request body)
- `msg`: A human-readable error message
- `type`: The type of validation error (e.g., `missing`, `value_error`, `type_error`)

# Localization

The API supports multiple languages and delivers localized content based on the Accept-Language header provided in HTTP requests. This ensures that responses are tailored to the individual language preferences of each user.

## Examples

### Single Language

```http
Accept-Language: es
```

### With Locale

```http
Accept-Language: en-GB
```

### Multiple Languages with Preferences

```http
Accept-Language: fr-CA, fr;q=0.8, en;q=0.5
```

# Pagination

The Karla API uses page-based pagination for endpoints that return collections of resources. This provides a simple and intuitive way to navigate through large datasets.

## Query Parameters

Paginated endpoints accept the following query parameters:

| Parameter  | Type    | Default | Description                        | Constraints |
| ---------- | ------- | ------- | ---------------------------------- | ----------- |
| `page`     | integer | 1       | The page number to retrieve        | Must be > 0 |
| `per_page` | integer | 30      | Number of items to return per page | 1-100 items |

## Example Request

```bash
curl https://api.gokarla.io/v1/shops/your-shop/orders?page=2&per_page=50 \
  -u your-username:your-private-api-key
```

## Response Format

Paginated responses return an array of items:

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_number": "ORD-2024-001",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "order_number": "ORD-2024-002",
    "created_at": "2024-01-15T11:00:00Z"
  }
]
```

## Best Practices

1. **Choose appropriate page sizes** - Larger pages reduce requests but increase response time
2. **Handle empty results** - The last page may contain fewer items than `per_page`
3. **Respect rate limits** - Pagination doesn't exempt you from rate limiting
4. **Cache when possible** - Results from earlier pages are unlikely to change frequently

# Versioning

When backwards-incompatible changes are made to the API, we release a new, dated version. GoKarla uses a date-based versioning scheme to ensure a predictable and stable API experience for developers.

## Version Format

API versions are named for the date of their release. For example, the API version `2024-01-05` was released on `Fri, 5 Jan 2024`.

## How to Specify a Version

You can configure your API version with the `Karla-Version` header. As a precaution, use API versioning to test a new API version before committing to an upgrade.

```jsx title="Request with Version Header"
curl https://api.gokarla.io/v1/shops/your-shop/campaigns \
  -u your-username:your-private-api-key \
  -H "Karla-Version: 2024-01-05"
```

## Default Behavior

Requests without the `Karla-Version` header, or with an invalid version, will default to use the latest stable version. This ensures backward compatibility while allowing developers to opt into specific versions when needed.

## Major Version Changes

For significant architectural changes, the base URL path will be updated:

- Current: `/v1/`
- Future: `/v2/`

Major version changes are rare and will be communicated well in advance with comprehensive migration guides and at least 1 year of deprecation notice.


## Servers

- `https://api.gokarla.io` — Production

## Endpoints

### GET /v1/deals

**List Deals**

Operation ID: `v1.deals.list`

List all deals.

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |

#### Responses
**200** — Successfully retrieved deals

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/orgs/{slug}

**Get Org**

Operation ID: `v1.orgs.get`

Search for shop orders (and its trackings if any) based on filters.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the org |

#### Responses
**200** — Get your current organization

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `any` | yes | The organization url slug |
| `name` | `any` | no | The organization name |
| `email` | `any` | no | The organization email |
| `phone` | `any` | no | The organization phone |
| `website` | `any` | no | The organization website |
| `industry` | `any` | no | The organization industry |
| `sso_domain` | `any` | no | The SSO domain |
| `feature_community` | `any` | yes | The feature community users of the organization belong to |
| `feature_toggles` | `any` | no | The specific features users have access to |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/orgs/{slug}/invite

**Invite User To Org**

Operation ID: `v1.orgs.invite`

Invite a user to an organization.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | Email of the user to invite |
| `role` | `"admin" \| "editor" \| "viewer"` | yes | The token permission scopes. |

#### Responses
**200** — Successfully invited user to organization

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/orgs/{slug}/members

**Search Org Members**

Operation ID: `v1.orgs.members.search`

Search for shop orders (and its trackings if any) based on filters.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the org |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |

#### Responses
**200** — List of org members that matches the search criteria

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops

**Search Shops**

Operation ID: `v1.shops.search`

Search shops based on some values to filter.

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `uuid` | `string` | no |  |
| `name` | `string` | no |  |
| `slug` | `string` | no |  |
| `shop_provider` | `"shopware" \| "shopify" \| "woocommerce" \| "api"` | no |  |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | no |  |
| `organization` | `string` | no |  |

#### Responses
**200** — Successfully retrieved shops

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops

**Create Shop**

Operation ID: `v1.shops.create`

Create a shop if it does not exist.

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | Name to display |
| `description` | `string` | no | Shop description dependant on user language |
| `organization` | `string` | no | Organization the shop belongs to (premium only) |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | no | Supported languages. |
| `contact_email` | `string` | no | Shop contact email address |
| `contact_phone` | `string` | no | Shop contact phone number |
| `industry` | `"clothing_and_accessories" \| "electronics" \| "food_and_drink" \| "health_and_beauty" \| "home_and_garden" \| "sports_and_recreation" \| "jewelry_and_accessories" \| "toys_and_games" \| "pet_care" \| "automotive" \| "books_and_media" \| "office_and_business" \| "arts_and_crafts" \| "baby_and_kids" \| "other"` | no | Industry category for a shop, based on Shopify industry list. |
| `shop_provider` | `"shopware" \| "shopify" \| "woocommerce" \| "api"` | no | Enum for identifying the shop provider of a merchant. |
| `shop_admin_url` | `string` | no | URL for API calls to the shop |
| `shop_faq_url` | `string` | no | URL for the FAQ page |
| `shop_service_url` | `string` | no | URL for the service page |
| `shop_url` | `string` | no | URL to the main shop |
| `logo_url` | `string` | no | Merchant logo image URL |
| `slug` | `string` | yes | Slug to filter |
| `settings` | `object` | no | Payload for creation of a new merchant. |
| `settings.klaviyo_triggers_enabled` | `boolean` | no | Will send klaviyo events for shipment updates |
| `settings.shopify_triggers_enabled` | `boolean` | no | Will send shopify events for shipment updates |
| `settings.carriers_enabled` | `boolean` | no | Will submit shipments to carriers for tracking |

#### Responses
**200** — Successfully created a shop

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The resource already exists or has conflicting information

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}

**Get Shop Detail**

Operation ID: `v1.shops.get`

Get details about a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | no | Time in which the resource was created |
| `updated_at` | `string` | no | Time in which the resource was last updated after creation |
| `uuid` | `string` | yes | Shop UUID |
| `name` | `string` | no | Name to display |
| `slug` | `string` | yes | Shop Slug |
| `organization` | `string` | no | Organization the shop belongs to |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | no | Supported languages. |
| `logo_url` | `string` | no | Merchant logo image URL |
| `shop_url` | `string` | no | URL to the main shop |
| `description` | `string` | no | Shop description dependant on user language |
| `contact_email` | `string` | no | Shop contact email address |
| `contact_phone` | `string` | no | Shop contact phone number |
| `industry` | `"clothing_and_accessories" \| "electronics" \| "food_and_drink" \| "health_and_beauty" \| "home_and_garden" \| "sports_and_recreation" \| "jewelry_and_accessories" \| "toys_and_games" \| "pet_care" \| "automotive" \| "books_and_media" \| "office_and_business" \| "arts_and_crafts" \| "baby_and_kids" \| "other"` | no | Industry category for a shop, based on Shopify industry list. |
| `shop_provider` | `"shopware" \| "shopify" \| "woocommerce" \| "api"` | no | Enum for identifying the shop provider of a merchant. |
| `shop_admin_url` | `string` | no | URL for API calls to the shop |
| `shop_faq_url` | `string` | no | URL for the FAQ page |
| `shop_service_url` | `string` | no | URL for the service page |
| `shop_currency` | `string` | no | Shop currency in ISO 4217 format, e.g. 'EUR', 'USD' |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}

**Update Shop**

Operation ID: `v1.shops.update`

Update a shop partially or completely.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | no | Name to display |
| `description` | `string` | no | Shop description dependant on user language |
| `organization` | `string` | no | Organization the shop belongs to |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | no | Supported languages. |
| `contact_email` | `string` | no | Shop contact email address |
| `contact_phone` | `string` | no | Shop contact phone number |
| `industry` | `"clothing_and_accessories" \| "electronics" \| "food_and_drink" \| "health_and_beauty" \| "home_and_garden" \| "sports_and_recreation" \| "jewelry_and_accessories" \| "toys_and_games" \| "pet_care" \| "automotive" \| "books_and_media" \| "office_and_business" \| "arts_and_crafts" \| "baby_and_kids" \| "other"` | no | Industry category for a shop, based on Shopify industry list. |
| `shop_provider` | `"shopware" \| "shopify" \| "woocommerce" \| "api"` | no | Enum for identifying the shop provider of a merchant. |
| `shop_admin_url` | `string` | no | URL for API calls to the shop |
| `shop_faq_url` | `string` | no | URL for the FAQ page |
| `shop_service_url` | `string` | no | URL for the service page |
| `shop_url` | `string` | no | URL to the main shop |
| `logo_url` | `string` | no | Merchant logo image URL |

#### Responses
**200** — Successfully updated a shop

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}

**Delete Shop**

Operation ID: `v1.shops.delete`

Delete a shop that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully deleted a shop

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/ab-tests

**List Ab Tests**

Operation ID: `v1.ab_tests.list`

List all AB tests for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The shop's unique identifier |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |

#### Responses
**200** — Successfully listed AB tests

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/ab-tests

**Create A/B Test**

Operation ID: `v1.ab_tests.create`

Create a new A/B test for campaign optimization.

    This endpoint allows to create A/B tests to experiment with different
    campaign variants and measure their performance.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The shop's unique identifier |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | Name of the AB test |
| `segment` | `string` | yes | Segment to which the AB test is targeted |
| `campaign_type` | `string` | yes | Type of campaign being tested |
| `campaigns` | `array<object>` | yes | List of campaigns and their allocations |
| `campaigns[].campaign_id` | `string` | yes | UUID of the campaign to include in the AB test |
| `campaigns[].allocation` | `integer` | yes | Percentage split for this campaign (0-100) |
| `has_holdout` | `boolean` | no | Whether to include a holdout group |
| `holdout_percentage` | `integer` | no | Percentage for the holdout group (0-100) |
| `start_date` | `string` | no | Time when the AB test will start |
| `end_date` | `string` | no | Time when the AB test will end |

#### Responses
**200** — Successfully created an AB test

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | AB test UUID |
| `name` | `string` | yes | Name of the AB test |
| `shop_slug` | `string` | yes | Shop slug |
| `segment` | `string` | yes | Segment to which the AB test is targeted |
| `campaign_type` | `string` | yes | Type of campaign being tested |
| `campaigns` | `array<object>` | yes | List of campaigns and their allocations |
| `campaigns[].enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `campaigns[].name` | `string` | yes | Campaign name to be used internally |
| `campaigns[].start_date` | `string` | yes | Time in which the campaign will start (defaults to now) |
| `campaigns[].end_date` | `string` | no | Time in which the campaign will end |
| `campaigns[].segment` | `string` | yes | Segment to which the campaign is targeted |
| `campaigns[].promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `campaigns[].promotion_properties` | `object \| object \| object` | yes |  |
| `campaigns[].uuid` | `string` | yes | Campaign UUID |
| `campaigns[].shop_slug` | `string` | yes | Shop Slug |
| `campaigns[].status` | `"active" \| "inactive" \| "scheduled" \| "paused"` | yes | State of the Campaign based on the start and end date. |
| `campaigns[].discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `campaigns[].discount.code` | `string` | no | Discount promotion code |
| `campaigns[].discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `campaigns[].discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `campaigns[].discount.title` | `string` | no | The customer facing name of the discount |
| `campaigns[].discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `campaigns[].discount.value` | `number` | no | Discount value based on its type |
| `campaigns[].discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `campaigns[].discount.uuid` | `string` | yes | Discount UUID |
| `campaigns[].allocation` | `integer` | yes | Percentage split for this campaign (0-100) |
| `has_holdout` | `boolean` | no | Whether the AB test includes a holdout group |
| `holdout_percentage` | `integer` | no | Percentage for the holdout group (0-100) |
| `start_date` | `string` | no | Time when the AB test started/will start |
| `end_date` | `string` | no | Time when the AB test ended/will end |
| `created_at` | `string` | yes | Time when the AB test was created |
| `updated_at` | `string` | yes | Time when the AB test was last updated |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find a campaign related to the given AB test

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The resource already exists or has conflicting information

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/ab-tests/{uuid}

**Get A/B Test Details**

Operation ID: `v1.ab_tests.get`

Retrieve detailed information about a specific A/B test.

    **Required permissions**: SuperAdmin role

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The shop's unique identifier |
| `uuid` | `string` | yes | The AB test's unique identifier |

#### Responses
**200** — Successfully retrieved AB test

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | AB test UUID |
| `name` | `string` | yes | Name of the AB test |
| `shop_slug` | `string` | yes | Shop slug |
| `segment` | `string` | yes | Segment to which the AB test is targeted |
| `campaign_type` | `string` | yes | Type of campaign being tested |
| `campaigns` | `array<object>` | yes | List of campaigns and their allocations |
| `campaigns[].enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `campaigns[].name` | `string` | yes | Campaign name to be used internally |
| `campaigns[].start_date` | `string` | yes | Time in which the campaign will start (defaults to now) |
| `campaigns[].end_date` | `string` | no | Time in which the campaign will end |
| `campaigns[].segment` | `string` | yes | Segment to which the campaign is targeted |
| `campaigns[].promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `campaigns[].promotion_properties` | `object \| object \| object` | yes |  |
| `campaigns[].uuid` | `string` | yes | Campaign UUID |
| `campaigns[].shop_slug` | `string` | yes | Shop Slug |
| `campaigns[].status` | `"active" \| "inactive" \| "scheduled" \| "paused"` | yes | State of the Campaign based on the start and end date. |
| `campaigns[].discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `campaigns[].discount.code` | `string` | no | Discount promotion code |
| `campaigns[].discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `campaigns[].discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `campaigns[].discount.title` | `string` | no | The customer facing name of the discount |
| `campaigns[].discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `campaigns[].discount.value` | `number` | no | Discount value based on its type |
| `campaigns[].discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `campaigns[].discount.uuid` | `string` | yes | Discount UUID |
| `campaigns[].allocation` | `integer` | yes | Percentage split for this campaign (0-100) |
| `has_holdout` | `boolean` | no | Whether the AB test includes a holdout group |
| `holdout_percentage` | `integer` | no | Percentage for the holdout group (0-100) |
| `start_date` | `string` | no | Time when the AB test started/will start |
| `end_date` | `string` | no | Time when the AB test ended/will end |
| `created_at` | `string` | yes | Time when the AB test was created |
| `updated_at` | `string` | yes | Time when the AB test was last updated |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the AB test

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/ab-tests/{uuid}/end-test

**End A/B Test**

Operation ID: `v1.ab_tests.end-test`

End an active A/B test and finalize the results.

    This action will stop assigning new users to test variants and mark
    the test as completed.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The shop's unique identifier |
| `uuid` | `string` | yes | The AB test's unique identifier |

#### Responses
**200** — Successfully ended AB test

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | AB test UUID |
| `name` | `string` | yes | Name of the AB test |
| `shop_slug` | `string` | yes | Shop slug |
| `segment` | `string` | yes | Segment to which the AB test is targeted |
| `campaign_type` | `string` | yes | Type of campaign being tested |
| `campaigns` | `array<object>` | yes | List of campaigns and their allocations |
| `campaigns[].enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `campaigns[].name` | `string` | yes | Campaign name to be used internally |
| `campaigns[].start_date` | `string` | yes | Time in which the campaign will start (defaults to now) |
| `campaigns[].end_date` | `string` | no | Time in which the campaign will end |
| `campaigns[].segment` | `string` | yes | Segment to which the campaign is targeted |
| `campaigns[].promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `campaigns[].promotion_properties` | `object \| object \| object` | yes |  |
| `campaigns[].uuid` | `string` | yes | Campaign UUID |
| `campaigns[].shop_slug` | `string` | yes | Shop Slug |
| `campaigns[].status` | `"active" \| "inactive" \| "scheduled" \| "paused"` | yes | State of the Campaign based on the start and end date. |
| `campaigns[].discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `campaigns[].discount.code` | `string` | no | Discount promotion code |
| `campaigns[].discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `campaigns[].discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `campaigns[].discount.title` | `string` | no | The customer facing name of the discount |
| `campaigns[].discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `campaigns[].discount.value` | `number` | no | Discount value based on its type |
| `campaigns[].discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `campaigns[].discount.uuid` | `string` | yes | Discount UUID |
| `campaigns[].allocation` | `integer` | yes | Percentage split for this campaign (0-100) |
| `has_holdout` | `boolean` | no | Whether the AB test includes a holdout group |
| `holdout_percentage` | `integer` | no | Percentage for the holdout group (0-100) |
| `start_date` | `string` | no | Time when the AB test started/will start |
| `end_date` | `string` | no | Time when the AB test ended/will end |
| `created_at` | `string` | yes | Time when the AB test was created |
| `updated_at` | `string` | yes | Time when the AB test was last updated |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the AB test

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/announcements

**Search Announcements**

Operation ID: `v1.announcements.search`

Search all announcements or based on some values to filter.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `uuid` | `string` | yes |  |
| `text` | `string` | yes |  |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | no |  |

#### Responses
**200** — Successfully retrieved announcements

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the announcement

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/announcements

**Create Announcement**

Operation ID: `v1.announcements.create`

Create an announcement if it does not exist.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | yes | Announcement text |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | yes | Supported languages. |

#### Responses
**200** — Successfully created an announcement

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the announcement

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The requested resource already exists!

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/announcements/{uuid}

**Update Announcement**

Operation ID: `v1.announcements.update`

Update an announcement partially or completely.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The announcement's unique identifier |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | no | Announcement text |
| `language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | no | Supported languages. |

#### Responses
**200** — Successfully updated an announcement

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/announcements/{uuid}

**Delete Announcement**

Operation ID: `v1.announcements.delete`

Delete an announcement that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The announcement's unique identifier |

#### Responses
**200** — Successfully deleted an announcement

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/api-keys

**List Api Keys**

Operation ID: `v1.shops.api_keys.list`

List all API keys for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved API keys

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | `string` | yes | The username holding the keys |
| `tokens` | `array<object>` | yes | Obfuscated tokens |
| `tokens[].id` | `string` | yes | Unique token identifier |
| `tokens[].secret` | `string` | yes | Obfuscated API key (e.g. sk_abcd...wxyz) |
| `tokens[].shops` | `array<object>` | yes | Shops the token has access to |
| `tokens[].shops[].shop_slug` | `string` | yes | The shop slug - if the slug is an * then it means all shops |
| `tokens[].shops[].role` | `"admin" \| "editor" \| "viewer"` | yes | The token permission scopes. |
| `tokens[].expiration` | `integer` | yes | Expiration time in Unix epoch (0 = never) |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/api-keys

**Create Api Key**

Operation ID: `v1.shops.api_keys.create`

Create a new API key scoped to the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `"admin" \| "editor" \| "viewer"` | no | The token permission scopes. |
| `expiration` | `integer` | no | Expiration time in Unix epoch (0 = never expires) |

#### Responses
**200** — Successfully processed operation

**201** — Successfully created an API key

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | Unique token identifier |
| `secret` | `string` | yes | Plaintext API key (shown only once) |
| `username` | `string` | yes | The username holding the key |
| `shops` | `array<object>` | yes | Shops the token has access to |
| `shops[].shop_slug` | `string` | yes | The shop slug - if the slug is an * then it means all shops |
| `shops[].role` | `"admin" \| "editor" \| "viewer"` | yes | The token permission scopes. |
| `expiration` | `integer` | yes | Expiration time in Unix epoch (0 = never) |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**429** — Rate limit or resource limit exceeded

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/api-keys

**Delete Api Key**

Operation ID: `v1.shops.api_keys.delete`

Delete an API key identified by its token ID.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token_id` | `string` | yes | Unique token identifier |

#### Responses
**200** — Successfully processed operation

**204** — Successful Response

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/billing

**Get Shop Billing**

Operation ID: `v1.shops.billing.get`

Get billing information for a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved shop billing information

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `subscription_tier` | `"free" \| "enterprise"` | yes | Subscription tier for a shop, derived from carrier settings. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/campaigns

**Search Campaigns**

Operation ID: `v1.campaigns.search`

Search all campaigns or based on some values to filter.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `uuid` | `string` | no |  |
| `name` | `string` | no |  |
| `start_date` | `string` | no |  |
| `end_date` | `string` | no |  |
| `segment` | `string` | no |  |
| `promotion_type` | `"product" \| "basic" \| "banner"` | no |  |
| `enabled` | `boolean` | no |  |

#### Responses
**200** — Successfully retrieved campaigns

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the campaign

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/campaigns

**Create Campaign**

Operation ID: `v1.campaigns.create`

Create a campaign if it does not exist.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `name` | `string` | yes | Campaign name to be used internally |
| `start_date` | `string` | no | Time in which the campaign will start (defaults to now) |
| `end_date` | `string` | no | Time in which the campaign will end |
| `segment` | `string` | yes | Segment to which the campaign is targeted |
| `promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `promotion_properties` | `object \| object \| object` | yes |  |
| `discount_id` | `string` | no | Discount UUID |

#### Responses
**200** — Successfully created a campaign

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `name` | `string` | yes | Campaign name to be used internally |
| `start_date` | `string` | yes | Time in which the campaign will start (defaults to now) |
| `end_date` | `string` | no | Time in which the campaign will end |
| `segment` | `string` | yes | Segment to which the campaign is targeted |
| `promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `promotion_properties` | `object \| object \| object` | yes |  |
| `uuid` | `string` | yes | Campaign UUID |
| `shop_slug` | `string` | yes | Shop Slug |
| `status` | `"active" \| "inactive" \| "scheduled" \| "paused"` | yes | State of the Campaign based on the start and end date. |
| `discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `discount.code` | `string` | no | Discount promotion code |
| `discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `discount.title` | `string` | no | The customer facing name of the discount |
| `discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `discount.value` | `number` | no | Discount value based on its type |
| `discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `discount.uuid` | `string` | yes | Discount UUID |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the campaign

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The resource already exists or has conflicting information

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/campaigns/order/{order_number}

**Get Campaign By Order Number**

Operation ID: `v1.campaigns.order.get`

Get campaigns for an order by order number.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `order_number` | `string` | yes | The order's unique identifier |

#### Responses
**200** — Successfully retrieved campaigns for order

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `banner` | `object` | no | The Campaign object to be exchanged with the HTTP clients. |
| `banner.enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `banner.name` | `string` | yes | Campaign name to be used internally |
| `banner.start_date` | `string` | yes | Time in which the campaign will start (defaults to now) |
| `banner.end_date` | `string` | no | Time in which the campaign will end |
| `banner.segment` | `string` | yes | Segment to which the campaign is targeted |
| `banner.promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `banner.promotion_properties` | `object \| object \| object` | yes |  |
| `banner.uuid` | `string` | yes | Campaign UUID |
| `banner.shop_slug` | `string` | yes | Shop Slug |
| `banner.status` | `"active" \| "inactive" \| "scheduled" \| "paused"` | yes | State of the Campaign based on the start and end date. |
| `banner.discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `banner.discount.code` | `string` | no | Discount promotion code |
| `banner.discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `banner.discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `banner.discount.title` | `string` | no | The customer facing name of the discount |
| `banner.discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `banner.discount.value` | `number` | no | Discount value based on its type |
| `banner.discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `banner.discount.uuid` | `string` | yes | Discount UUID |
| `basic` | `object` | no | The Campaign object to be exchanged with the HTTP clients. |
| `product` | `object` | no | The Campaign object to be exchanged with the HTTP clients. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find campaigns related to the given order

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/campaigns/{uuid}

**Update Campaign**

Operation ID: `v1.campaigns.update`

Update a campaign completely.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The campaign's unique identifier |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `name` | `string` | yes | Campaign name to be used internally |
| `start_date` | `string` | no | Time in which the campaign will start (defaults to now) |
| `end_date` | `string` | no | Time in which the campaign will end |
| `segment` | `string` | yes | Segment to which the campaign is targeted |
| `promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `promotion_properties` | `object \| object \| object` | yes |  |
| `discount_id` | `string` | no | Discount UUID |

#### Responses
**200** — Successfully updated a campaign

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | no | Campaign visibility toggle. Only one campaign can be enabled per segment at a time. |
| `name` | `string` | yes | Campaign name to be used internally |
| `start_date` | `string` | yes | Time in which the campaign will start (defaults to now) |
| `end_date` | `string` | no | Time in which the campaign will end |
| `segment` | `string` | yes | Segment to which the campaign is targeted |
| `promotion_type` | `"product" \| "basic" \| "banner"` | yes | Type of the Campaign to store. |
| `promotion_properties` | `object \| object \| object` | yes |  |
| `uuid` | `string` | yes | Campaign UUID |
| `shop_slug` | `string` | yes | Shop Slug |
| `status` | `"active" \| "inactive" \| "scheduled" \| "paused"` | yes | State of the Campaign based on the start and end date. |
| `discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `discount.code` | `string` | no | Discount promotion code |
| `discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `discount.title` | `string` | no | The customer facing name of the discount |
| `discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `discount.value` | `number` | no | Discount value based on its type |
| `discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `discount.uuid` | `string` | yes | Discount UUID |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the campaign

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/campaigns/{uuid}

**Delete Campaign**

Operation ID: `v1.campaigns.delete`

Delete a campaign that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The campaign's unique identifier |

#### Responses
**200** — Successfully deleted a campaign

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the campaign

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/claims

**Search Claims**

Operation ID: `v1.claims.search`

Search all claims or based on some values to filter.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `order_id` | `string` | no |  |
| `shipment_id` | `string` | no |  |
| `resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no |  |
| `status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no |  |
| `reason` | `"partial_damage" \| "damage" \| "investigation" \| "support" \| "return" \| "dissatisfied_with_product" \| "wrong_product" \| "missing_product"` | no |  |
| `created_from` | `string` | no |  |
| `created_to` | `string` | no |  |
| `updated_from` | `string` | no |  |
| `updated_to` | `string` | no |  |
| `sort` | `string` | no |  |

#### Responses
**200** — Paginated list of claims matching the search criteria

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `claims` | `array<object>` | yes | List of claims |
| `claims[].created_at` | `string` | no | When the resource was created |
| `claims[].updated_at` | `string` | no | When the resource was last updated |
| `claims[].deleted_at` | `any` | no |  |
| `claims[].uuid` | `string` | yes | Claim UUID |
| `claims[].order_id` | `string` | no | Order UUID |
| `claims[].shipment_id` | `string` | no | Shipment UUID |
| `claims[].shop_id` | `string` | yes | Shop UUID |
| `claims[].order_number` | `string` | no | Order number related to the shop |
| `claims[].resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no | Type resolution preference for a claim. |
| `claims[].reason` | `"partial_damage" \| "damage" \| "investigation" \| "support" \| "return" \| "dissatisfied_with_product" \| "wrong_product" \| "missing_product"` | yes | Type reason for a claim. |
| `claims[].status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no | Type status for a claim. |
| `claims[].description` | `string` | no | Complimentary description to explain why the claim was submitted |
| `claims[].customer_signature_image_url` | `string` | no | The private image url with the client signature |
| `claims[].damaged_product_items` | `array<object>` | no | List of damaged product items (DEPRECATED) |
| `claims[].damaged_product_items[].sku` | `string` | no | SKU of the product item |
| `claims[].damaged_product_items[].title` | `string` | no | Product title |
| `claims[].damaged_product_items[].quantity` | `integer` | yes | Quantity of the product item |
| `claims[].damaged_product_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `claims[].damaged_product_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `claims[].selected_items` | `array<object>` | no | List of selected product items |
| `claims[].selected_items[].sku` | `string` | no | SKU of the product item |
| `claims[].selected_items[].title` | `string` | no | Product title |
| `claims[].selected_items[].quantity` | `integer` | yes | Quantity of the product item |
| `claims[].selected_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `claims[].selected_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `claims[].image_urls` | `array<string>` | no | List of image urls |
| `claims[].optional_image_urls` | `array<string>` | no | List of image urls classified as optional (not required for the claim but that may help to resolve it) |
| `claims[].address` | `object` | no | Schema for standardized address objects. |
| `claims[].address.address_line_1` | `string` | no | The resident's mailing address |
| `claims[].address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `claims[].address.city` | `string` | no | The resident's city |
| `claims[].address.country` | `string` | no | The resident's country |
| `claims[].address.country_code` | `string` | no | The two letter digit resident's country code |
| `claims[].address.name` | `string` | no | The first and last names of the resident |
| `claims[].address.phone` | `string` | no | The resident's phone number |
| `claims[].address.province` | `string` | no | The resident's province or state name |
| `claims[].address.province_code` | `string` | no | The resident's province or state name |
| `claims[].address.street` | `string` | no | A combination of the first and second lines of the address |
| `claims[].address.zip_code` | `string` | no | The address zip or postal code |
| `claims[].net_invoice_amount` | `number` | no | Price of the entire order without discounts, shipping costs and taxes applied |
| `claims[].tracking_number` | `string` | no | Carrier Tracking Number |
| `claims[].carrier_reference` | `"dhl" \| "dhl_ecommerce_nl" \| "dhlexp" \| "dhl_old" \| "dhl2man" \| "deutsche_post_mail" \| "amazon" \| "brt" \| "dpd" \| "dpdn" \| "dpd-at" \| "dpd-ch" \| "dpduk" \| "dpd-de" \| "gls" \| "gls_es" \| "gls_it" \| "gls_express" \| "goexp" \| "hrs" \| "postat" \| "rhe" \| "royalmail" \| "swisspost" \| "ups" \| "bpost" \| "dao" \| "anpost" \| "bring" \| "posti" \| "postnl" \| "postnl_inter" \| "usps" \| "fedex" \| "fedex_uk" \| "fedex_freight" \| "postnord" \| "parcelone" \| "dachser" \| "asendia_de" \| "colissimo" \| "inpost_uk" \| "inpost_pl" \| "inpost_it" \| "mondial_relay" \| "evri" \| "poste_italiane" \| "kuehne-nagel" \| "dsv" \| "ait_usa" \| "ait_uk" \| "colis_prive" \| "dynalogic" \| "correos_es" \| "landmark_global" \| "ppl_cz" \| "karl_juergersen" \| "hellmann"` | no | All Carriers Supported. |
| `claims[].scan_date` | `string` | no | Date the package was picked by the carrier |
| `claims[].weight_kg` | `number` | no | The weight of the package in kilograms |
| `claims[].dropoff_permission` | `boolean` | no | The customer's response about whether they authorized the carrier to leave the package at a designated spot without requiring direct delivery |
| `claims[].step_user_input` | `array<object>` | no | User input for each step in the claim process |
| `claims[].step_user_input[].step_id` | `string` | yes | Unique identifier for the step |
| `claims[].step_user_input[].user_input` | `object` | yes | User input for a claim. |
| `claims[].step_user_input[].user_input.input_type` | `"selected_answer" \| "user_answer"` | yes | Enum for order reference types. |
| `claims[].step_user_input[].user_input.input_value` | `string` | yes | Value written by the user or id if the user selected an answer depending on input type |
| `claims[].step_user_input[].user_input.translated_question` | `string` | no | Question translated to the shop's language |
| `claims[].step_user_input[].user_input.translated_answer` | `string` | no | Answer translated to the shop's language (if answer is selected by the user) |
| `claims[].shop_slug` | `string` | yes | Shop identifier as a url slug |
| `pagination` | `object` | yes | Pagination metadata for API responses. |
| `pagination.page` | `integer` | yes | Current page number |
| `pagination.per_page` | `integer` | yes | Items per page |
| `pagination.total` | `integer` | yes | Total number of items |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/claims

**Create Claim**

Operation ID: `v1.claims.create`

Create a claim if it does not exist.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no | Type resolution preference for a claim. |
| `reason` | `"partial_damage" \| "damage" \| "investigation" \| "support" \| "return" \| "dissatisfied_with_product" \| "wrong_product" \| "missing_product"` | yes | Type reason for a claim. |
| `status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no | Type status for a claim. |
| `description` | `string` | no | Complimentary description to explain why the claim was submitted |
| `customer_signature_image_url` | `string` | no | The private image url with the client signature |
| `selected_items` | `array<object>` | no | List of selected product items |
| `selected_items[].sku` | `string` | no | SKU of the product item |
| `selected_items[].title` | `string` | no | Product title |
| `selected_items[].quantity` | `integer` | yes | Quantity of the product item |
| `selected_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `selected_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `image_urls` | `array<string>` | no | List of image URLs that give evidence of the damaged product or claim in general |
| `optional_image_urls` | `array<string>` | no | List of image urls classified as optional (not required for the claim but that may help to resolve it) |
| `dropoff_permission` | `boolean` | no | The customer's response about whether they authorized the carrier to leave the package at a designated spot without requiring direct delivery |
| `step_user_input` | `array<object>` | no | User input for each step in the claim process |
| `step_user_input[].step_id` | `string` | yes | Unique identifier for the step |
| `step_user_input[].user_input` | `object` | yes | User input for a claim. |
| `step_user_input[].user_input.input_type` | `"selected_answer" \| "user_answer"` | yes | Enum for order reference types. |
| `step_user_input[].user_input.input_value` | `string` | yes | Value written by the user or id if the user selected an answer depending on input type |
| `step_user_input[].user_input.translated_question` | `string` | no | Question translated to the shop's language |
| `step_user_input[].user_input.translated_answer` | `string` | no | Answer translated to the shop's language (if answer is selected by the user) |
| `shipment_id` | `string` | no | Unique identifier for the system in Karla. If not provided, a tracking number has to be given. |
| `damaged_product_items` | `array<object>` | no | List of damaged product items (DEPRECATED) |
| `damaged_product_items[].sku` | `string` | no | SKU of the product item |
| `damaged_product_items[].title` | `string` | no | Product title |
| `damaged_product_items[].quantity` | `integer` | yes | Quantity of the product item |
| `damaged_product_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `damaged_product_items[].image_urls` | `array<string>` | no | List of image URLs of the product |

#### Responses
**200** — Successfully created a claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | no | When the resource was created |
| `updated_at` | `string` | no | When the resource was last updated |
| `deleted_at` | `any` | no |  |
| `uuid` | `string` | yes | Claim UUID |
| `order_id` | `string` | no | Order UUID |
| `shipment_id` | `string` | no | Shipment UUID |
| `shop_id` | `string` | yes | Shop UUID |
| `order_number` | `string` | no | Order number related to the shop |
| `resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no | Type resolution preference for a claim. |
| `reason` | `"partial_damage" \| "damage" \| "investigation" \| "support" \| "return" \| "dissatisfied_with_product" \| "wrong_product" \| "missing_product"` | yes | Type reason for a claim. |
| `status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no | Type status for a claim. |
| `description` | `string` | no | Complimentary description to explain why the claim was submitted |
| `customer_signature_image_url` | `string` | no | The private image url with the client signature |
| `damaged_product_items` | `array<object>` | no | List of damaged product items (DEPRECATED) |
| `damaged_product_items[].sku` | `string` | no | SKU of the product item |
| `damaged_product_items[].title` | `string` | no | Product title |
| `damaged_product_items[].quantity` | `integer` | yes | Quantity of the product item |
| `damaged_product_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `damaged_product_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `selected_items` | `array<object>` | no | List of selected product items |
| `selected_items[].sku` | `string` | no | SKU of the product item |
| `selected_items[].title` | `string` | no | Product title |
| `selected_items[].quantity` | `integer` | yes | Quantity of the product item |
| `selected_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `selected_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `image_urls` | `array<string>` | no | List of image urls |
| `optional_image_urls` | `array<string>` | no | List of image urls classified as optional (not required for the claim but that may help to resolve it) |
| `address` | `object` | no | Schema for standardized address objects. |
| `address.address_line_1` | `string` | no | The resident's mailing address |
| `address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `address.city` | `string` | no | The resident's city |
| `address.country` | `string` | no | The resident's country |
| `address.country_code` | `string` | no | The two letter digit resident's country code |
| `address.name` | `string` | no | The first and last names of the resident |
| `address.phone` | `string` | no | The resident's phone number |
| `address.province` | `string` | no | The resident's province or state name |
| `address.province_code` | `string` | no | The resident's province or state name |
| `address.street` | `string` | no | A combination of the first and second lines of the address |
| `address.zip_code` | `string` | no | The address zip or postal code |
| `net_invoice_amount` | `number` | no | Price of the entire order without discounts, shipping costs and taxes applied |
| `tracking_number` | `string` | no | Carrier Tracking Number |
| `carrier_reference` | `"dhl" \| "dhl_ecommerce_nl" \| "dhlexp" \| "dhl_old" \| "dhl2man" \| "deutsche_post_mail" \| "amazon" \| "brt" \| "dpd" \| "dpdn" \| "dpd-at" \| "dpd-ch" \| "dpduk" \| "dpd-de" \| "gls" \| "gls_es" \| "gls_it" \| "gls_express" \| "goexp" \| "hrs" \| "postat" \| "rhe" \| "royalmail" \| "swisspost" \| "ups" \| "bpost" \| "dao" \| "anpost" \| "bring" \| "posti" \| "postnl" \| "postnl_inter" \| "usps" \| "fedex" \| "fedex_uk" \| "fedex_freight" \| "postnord" \| "parcelone" \| "dachser" \| "asendia_de" \| "colissimo" \| "inpost_uk" \| "inpost_pl" \| "inpost_it" \| "mondial_relay" \| "evri" \| "poste_italiane" \| "kuehne-nagel" \| "dsv" \| "ait_usa" \| "ait_uk" \| "colis_prive" \| "dynalogic" \| "correos_es" \| "landmark_global" \| "ppl_cz" \| "karl_juergersen" \| "hellmann"` | no | All Carriers Supported. |
| `scan_date` | `string` | no | Date the package was picked by the carrier |
| `weight_kg` | `number` | no | The weight of the package in kilograms |
| `dropoff_permission` | `boolean` | no | The customer's response about whether they authorized the carrier to leave the package at a designated spot without requiring direct delivery |
| `step_user_input` | `array<object>` | no | User input for each step in the claim process |
| `step_user_input[].step_id` | `string` | yes | Unique identifier for the step |
| `step_user_input[].user_input` | `object` | yes | User input for a claim. |
| `step_user_input[].user_input.input_type` | `"selected_answer" \| "user_answer"` | yes | Enum for order reference types. |
| `step_user_input[].user_input.input_value` | `string` | yes | Value written by the user or id if the user selected an answer depending on input type |
| `step_user_input[].user_input.translated_question` | `string` | no | Question translated to the shop's language |
| `step_user_input[].user_input.translated_answer` | `string` | no | Answer translated to the shop's language (if answer is selected by the user) |
| `shop_slug` | `string` | yes | Shop identifier as a url slug |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The resource already exists or has conflicting information

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/claims/{uuid}

**Get Claim**

Operation ID: `v1.claims.get`

Get a single claim by its unique identifier.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The claim's unique identifier |

#### Responses
**200** — Successfully retrieved a claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | no | When the resource was created |
| `updated_at` | `string` | no | When the resource was last updated |
| `deleted_at` | `any` | no |  |
| `uuid` | `string` | yes | Claim UUID |
| `order_id` | `string` | no | Order UUID |
| `shipment_id` | `string` | no | Shipment UUID |
| `shop_id` | `string` | yes | Shop UUID |
| `order_number` | `string` | no | Order number related to the shop |
| `resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no | Type resolution preference for a claim. |
| `reason` | `"partial_damage" \| "damage" \| "investigation" \| "support" \| "return" \| "dissatisfied_with_product" \| "wrong_product" \| "missing_product"` | yes | Type reason for a claim. |
| `status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no | Type status for a claim. |
| `description` | `string` | no | Complimentary description to explain why the claim was submitted |
| `customer_signature_image_url` | `string` | no | The private image url with the client signature |
| `damaged_product_items` | `array<object>` | no | List of damaged product items (DEPRECATED) |
| `damaged_product_items[].sku` | `string` | no | SKU of the product item |
| `damaged_product_items[].title` | `string` | no | Product title |
| `damaged_product_items[].quantity` | `integer` | yes | Quantity of the product item |
| `damaged_product_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `damaged_product_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `selected_items` | `array<object>` | no | List of selected product items |
| `selected_items[].sku` | `string` | no | SKU of the product item |
| `selected_items[].title` | `string` | no | Product title |
| `selected_items[].quantity` | `integer` | yes | Quantity of the product item |
| `selected_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `selected_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `image_urls` | `array<string>` | no | List of image urls |
| `optional_image_urls` | `array<string>` | no | List of image urls classified as optional (not required for the claim but that may help to resolve it) |
| `address` | `object` | no | Schema for standardized address objects. |
| `address.address_line_1` | `string` | no | The resident's mailing address |
| `address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `address.city` | `string` | no | The resident's city |
| `address.country` | `string` | no | The resident's country |
| `address.country_code` | `string` | no | The two letter digit resident's country code |
| `address.name` | `string` | no | The first and last names of the resident |
| `address.phone` | `string` | no | The resident's phone number |
| `address.province` | `string` | no | The resident's province or state name |
| `address.province_code` | `string` | no | The resident's province or state name |
| `address.street` | `string` | no | A combination of the first and second lines of the address |
| `address.zip_code` | `string` | no | The address zip or postal code |
| `net_invoice_amount` | `number` | no | Price of the entire order without discounts, shipping costs and taxes applied |
| `tracking_number` | `string` | no | Carrier Tracking Number |
| `carrier_reference` | `"dhl" \| "dhl_ecommerce_nl" \| "dhlexp" \| "dhl_old" \| "dhl2man" \| "deutsche_post_mail" \| "amazon" \| "brt" \| "dpd" \| "dpdn" \| "dpd-at" \| "dpd-ch" \| "dpduk" \| "dpd-de" \| "gls" \| "gls_es" \| "gls_it" \| "gls_express" \| "goexp" \| "hrs" \| "postat" \| "rhe" \| "royalmail" \| "swisspost" \| "ups" \| "bpost" \| "dao" \| "anpost" \| "bring" \| "posti" \| "postnl" \| "postnl_inter" \| "usps" \| "fedex" \| "fedex_uk" \| "fedex_freight" \| "postnord" \| "parcelone" \| "dachser" \| "asendia_de" \| "colissimo" \| "inpost_uk" \| "inpost_pl" \| "inpost_it" \| "mondial_relay" \| "evri" \| "poste_italiane" \| "kuehne-nagel" \| "dsv" \| "ait_usa" \| "ait_uk" \| "colis_prive" \| "dynalogic" \| "correos_es" \| "landmark_global" \| "ppl_cz" \| "karl_juergersen" \| "hellmann"` | no | All Carriers Supported. |
| `scan_date` | `string` | no | Date the package was picked by the carrier |
| `weight_kg` | `number` | no | The weight of the package in kilograms |
| `dropoff_permission` | `boolean` | no | The customer's response about whether they authorized the carrier to leave the package at a designated spot without requiring direct delivery |
| `step_user_input` | `array<object>` | no | User input for each step in the claim process |
| `step_user_input[].step_id` | `string` | yes | Unique identifier for the step |
| `step_user_input[].user_input` | `object` | yes | User input for a claim. |
| `step_user_input[].user_input.input_type` | `"selected_answer" \| "user_answer"` | yes | Enum for order reference types. |
| `step_user_input[].user_input.input_value` | `string` | yes | Value written by the user or id if the user selected an answer depending on input type |
| `step_user_input[].user_input.translated_question` | `string` | no | Question translated to the shop's language |
| `step_user_input[].user_input.translated_answer` | `string` | no | Answer translated to the shop's language (if answer is selected by the user) |
| `shop_slug` | `string` | yes | Shop identifier as a url slug |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/claims/{uuid}

**Update Claim**

Operation ID: `v1.claims.update`

Modify an existing claim.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The claim's unique identifier |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no | Type resolution preference for a claim. |
| `status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no | Type status for a claim. |

#### Responses
**200** — Successfully updated a claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | no | When the resource was created |
| `updated_at` | `string` | no | When the resource was last updated |
| `deleted_at` | `any` | no |  |
| `uuid` | `string` | yes | Claim UUID |
| `order_id` | `string` | no | Order UUID |
| `shipment_id` | `string` | no | Shipment UUID |
| `shop_id` | `string` | yes | Shop UUID |
| `order_number` | `string` | no | Order number related to the shop |
| `resolution_preference` | `"reorder" \| "refund" \| "keep_with_reward"` | no | Type resolution preference for a claim. |
| `reason` | `"partial_damage" \| "damage" \| "investigation" \| "support" \| "return" \| "dissatisfied_with_product" \| "wrong_product" \| "missing_product"` | yes | Type reason for a claim. |
| `status` | `"pending" \| "accepted" \| "rejected" \| "closed"` | no | Type status for a claim. |
| `description` | `string` | no | Complimentary description to explain why the claim was submitted |
| `customer_signature_image_url` | `string` | no | The private image url with the client signature |
| `damaged_product_items` | `array<object>` | no | List of damaged product items (DEPRECATED) |
| `damaged_product_items[].sku` | `string` | no | SKU of the product item |
| `damaged_product_items[].title` | `string` | no | Product title |
| `damaged_product_items[].quantity` | `integer` | yes | Quantity of the product item |
| `damaged_product_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `damaged_product_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `selected_items` | `array<object>` | no | List of selected product items |
| `selected_items[].sku` | `string` | no | SKU of the product item |
| `selected_items[].title` | `string` | no | Product title |
| `selected_items[].quantity` | `integer` | yes | Quantity of the product item |
| `selected_items[].net_price` | `number` | no | Price of the product without a discount and taxes applied |
| `selected_items[].image_urls` | `array<string>` | no | List of image URLs of the product |
| `image_urls` | `array<string>` | no | List of image urls |
| `optional_image_urls` | `array<string>` | no | List of image urls classified as optional (not required for the claim but that may help to resolve it) |
| `address` | `object` | no | Schema for standardized address objects. |
| `address.address_line_1` | `string` | no | The resident's mailing address |
| `address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `address.city` | `string` | no | The resident's city |
| `address.country` | `string` | no | The resident's country |
| `address.country_code` | `string` | no | The two letter digit resident's country code |
| `address.name` | `string` | no | The first and last names of the resident |
| `address.phone` | `string` | no | The resident's phone number |
| `address.province` | `string` | no | The resident's province or state name |
| `address.province_code` | `string` | no | The resident's province or state name |
| `address.street` | `string` | no | A combination of the first and second lines of the address |
| `address.zip_code` | `string` | no | The address zip or postal code |
| `net_invoice_amount` | `number` | no | Price of the entire order without discounts, shipping costs and taxes applied |
| `tracking_number` | `string` | no | Carrier Tracking Number |
| `carrier_reference` | `"dhl" \| "dhl_ecommerce_nl" \| "dhlexp" \| "dhl_old" \| "dhl2man" \| "deutsche_post_mail" \| "amazon" \| "brt" \| "dpd" \| "dpdn" \| "dpd-at" \| "dpd-ch" \| "dpduk" \| "dpd-de" \| "gls" \| "gls_es" \| "gls_it" \| "gls_express" \| "goexp" \| "hrs" \| "postat" \| "rhe" \| "royalmail" \| "swisspost" \| "ups" \| "bpost" \| "dao" \| "anpost" \| "bring" \| "posti" \| "postnl" \| "postnl_inter" \| "usps" \| "fedex" \| "fedex_uk" \| "fedex_freight" \| "postnord" \| "parcelone" \| "dachser" \| "asendia_de" \| "colissimo" \| "inpost_uk" \| "inpost_pl" \| "inpost_it" \| "mondial_relay" \| "evri" \| "poste_italiane" \| "kuehne-nagel" \| "dsv" \| "ait_usa" \| "ait_uk" \| "colis_prive" \| "dynalogic" \| "correos_es" \| "landmark_global" \| "ppl_cz" \| "karl_juergersen" \| "hellmann"` | no | All Carriers Supported. |
| `scan_date` | `string` | no | Date the package was picked by the carrier |
| `weight_kg` | `number` | no | The weight of the package in kilograms |
| `dropoff_permission` | `boolean` | no | The customer's response about whether they authorized the carrier to leave the package at a designated spot without requiring direct delivery |
| `step_user_input` | `array<object>` | no | User input for each step in the claim process |
| `step_user_input[].step_id` | `string` | yes | Unique identifier for the step |
| `step_user_input[].user_input` | `object` | yes | User input for a claim. |
| `step_user_input[].user_input.input_type` | `"selected_answer" \| "user_answer"` | yes | Enum for order reference types. |
| `step_user_input[].user_input.input_value` | `string` | yes | Value written by the user or id if the user selected an answer depending on input type |
| `step_user_input[].user_input.translated_question` | `string` | no | Question translated to the shop's language |
| `step_user_input[].user_input.translated_answer` | `string` | no | Answer translated to the shop's language (if answer is selected by the user) |
| `shop_slug` | `string` | yes | Shop identifier as a url slug |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/claims/{uuid}

**Delete Claim**

Operation ID: `v1.claims.delete`

Delete a claim that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The claim's unique identifier |

#### Responses
**200** — Successfully deleted a claim

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find the claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/deals

**List Shop Deals**

Operation ID: `v1.deals.shop.list`

List all deals for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |

#### Responses
**200** — Successfully retrieved deals

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Shop not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/deals

**Create Deal**

Operation ID: `v1.deals.create`

Create a deal for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `discount_id` | `string` | yes | Discount UUID |
| `brand_image_url` | `string` | no | Brand image URL |
| `brand_logo_url` | `string` | no | Brand logo URL |
| `cta_url` | `string` | no | CTA URL |
| `title` | `string` | no | Title |
| `description` | `string` | no | Description |
| `translations` | `array<object>` | no | Translations |
| `translations[].language` | `string` | yes |  |
| `translations[].data` | `object` | yes |  |

#### Responses
**200** — Successfully created deal

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | Deal UUID |
| `shop_slug` | `string` | yes | Shop slug |
| `shop_name` | `string` | yes | Shop name |
| `discount_id` | `string` | yes | Discount UUID |
| `brand_image_url` | `string` | yes | Brand image URL |
| `brand_logo_url` | `string` | yes | Brand logo URL |
| `cta_url` | `string` | yes | CTA URL |
| `title` | `string` | yes | Title |
| `description` | `string` | yes | Description |
| `rank` | `integer` | no | Rank |
| `discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `discount.code` | `string` | no | Discount promotion code |
| `discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `discount.title` | `string` | no | The customer facing name of the discount |
| `discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `discount.value` | `number` | no | Discount value based on its type |
| `discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `discount.uuid` | `string` | yes | Discount UUID |
| `translations` | `array<object>` | no | All translations without language filtering |
| `translations[].language` | `string` | yes |  |
| `translations[].data` | `object` | yes |  |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Shop not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/deals/{deal_id}

**Update Deal**

Operation ID: `v1.deals.update`

Update a deal for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `deal_id` | `string` | yes | The ID of the deal |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `discount_id` | `string` | no | Discount UUID |
| `brand_image_url` | `string` | no | Brand image URL |
| `brand_logo_url` | `string` | no | Brand logo URL |
| `cta_url` | `string` | no | CTA URL |
| `title` | `string` | no | Title |
| `description` | `string` | no | Description |
| `translations` | `array<object>` | no | Translations |
| `translations[].language` | `string` | yes |  |
| `translations[].data` | `object` | yes |  |

#### Responses
**200** — Successfully updated deal

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | Deal UUID |
| `shop_slug` | `string` | yes | Shop slug |
| `shop_name` | `string` | yes | Shop name |
| `discount_id` | `string` | yes | Discount UUID |
| `brand_image_url` | `string` | yes | Brand image URL |
| `brand_logo_url` | `string` | yes | Brand logo URL |
| `cta_url` | `string` | yes | CTA URL |
| `title` | `string` | yes | Title |
| `description` | `string` | yes | Description |
| `rank` | `integer` | no | Rank |
| `discount` | `object` | no | The Discount entity to be used in DTOs like nested objects. |
| `discount.code` | `string` | no | Discount promotion code |
| `discount.target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `discount.target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `discount.title` | `string` | no | The customer facing name of the discount |
| `discount.value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `discount.value` | `number` | no | Discount value based on its type |
| `discount.type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |
| `discount.uuid` | `string` | yes | Discount UUID |
| `translations` | `array<object>` | no | All translations without language filtering |
| `translations[].language` | `string` | yes |  |
| `translations[].data` | `object` | yes |  |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Deal not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/deals/{deal_id}

**Delete Deal**

Operation ID: `v1.deals.delete`

Delete a deal for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `deal_id` | `string` | yes | The ID of the deal |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted deal

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Deal not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/discounts

**Search Discounts**

Operation ID: `v1.discounts.search`

Search all discounts or based on some values to filter.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | no |  |
| `target_selection` | `"all" \| "group" \| "specific"` | no |  |
| `target_type` | `"line_item" \| "shipping_line"` | no |  |
| `title` | `string` | no |  |
| `value_type` | `"percentage" \| "fixed_amount"` | no |  |
| `value` | `number` | no |  |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `uuid` | `string` | no |  |
| `type` | `"product" \| "order" \| "shipping"` | no |  |

#### Responses
**200** — Successfully retrieved discounts

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the discount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/discounts

**Create Discount**

Operation ID: `v1.discounts.create`

Create a discount if it does not exist.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | no | Discount promotion code |
| `target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `title` | `string` | no | The customer facing name of the discount |
| `value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `value` | `number` | no | Discount value based on its type |
| `type` | `"product" \| "order" \| "shipping"` | yes | Type of discount. |

#### Responses
**200** — Successfully created a discount

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the discount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The resource already exists or has conflicting information

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/discounts/{uuid}

**Update Discount**

Operation ID: `v1.discounts.update`

Update a discount partially or completely.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The discount's unique identifier |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | no | Discount promotion code |
| `target_selection` | `"all" \| "group" \| "specific"` | no | Selection method for line items or shipping lines to be discounted. |
| `target_type` | `"line_item" \| "shipping_line"` | no | Type of item that the discount applies to.. |
| `title` | `string` | no | The customer facing name of the discount |
| `value_type` | `"percentage" \| "fixed_amount"` | no | Type of value for order and product discounts. |
| `value` | `number` | no | Discount value based on its type |

#### Responses
**200** — Successfully updated a discount

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/discounts/{uuid}

**Delete Discount**

Operation ID: `v1.discounts.delete`

Delete a discount that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The discount's unique identifier |

#### Responses
**200** — Successfully deleted a discount

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/images/{image_type}

**Upload Shop Image**

Operation ID: `v1.shops.images.upload`

Upload an image for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `image_type` | `"background" \| "claim" \| "logo" \| "signature" \| "product" \| "voucher"` | yes | The type of image to upload |

#### Responses
**200** — Successfully uploaded a shop image

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | yes | The public url of the uploaded image |
| `image_type` | `"background" \| "claim" \| "logo" \| "signature" \| "product" \| "voucher"` | yes | Type of image that is allowed by the system. |
| `shop_slug` | `string` | yes | The slug of the shop the image belongs to |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/keys

**List Keys**

Operation ID: `v1.shops.keys.list`

List all integration keys for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `brevo` | `string` | no | Key used for the Brevo integration (only last 6 characters will be visible) |
| `klaviyo` | `string` | no | Key used for the Klaviyo integration (only last 3 characters will be visible) |
| `shopify` | `string` | no | Key used for the Shopify integration (only last 6 characters will be visible) |
| `shopware` | `object` | no | Schema for a client id and client key secret. |
| `shopware.client_id` | `any` | yes | The client id |
| `shopware.client_secret` | `any` | no | The client secret |
| `emarsys` | `object` | no | Schema for a client id and client key secret. |
| `inxmail` | `object` | no | Basic authentication credentials with username and password. |
| `inxmail.username` | `string` | yes | The username for basic auth |
| `inxmail.password` | `string` | yes | The password for basic auth |
| `hubspot` | `string` | no | Key used for the HubSpot integration (only last 6 characters will be visible) |
| `braze` | `string` | no | Key used for the Braze integration (only last 6 characters will be visible) |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/braze

**Set Braze Api Key**

Operation ID: `v1.shops.keys.braze.set`

Set a Braze API key for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `string` | yes | The api key |

#### Responses
**200** — Successfully set Braze API key

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/brevo

**Set Brevo Api Key**

Operation ID: `v1.shops.keys.brevo.set`

Set a Brevo API key for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `string` | yes | The api key |

#### Responses
**200** — Successfully set Brevo API key

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/emarsys

**Set Emarsys Api Credentials**

Operation ID: `v1.shops.keys.emarsys.set`

Set emarsys api credentials for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | `string` | yes | The client id |
| `client_secret` | `string` | no | The client secret |

#### Responses
**200** — Successfully set Emarsys API credentials

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/hubspot

**Set Hubspot Api Key**

Operation ID: `v1.shops.keys.hubspot.set`

Set a HubSpot Private App access token for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `string` | yes | The api key |

#### Responses
**200** — Successfully set HubSpot API key

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/inxmail

**Set Inxmail Basic Auth**

Operation ID: `v1.shops.keys.inxmail.set`

Set Inxmail basic auth credentials for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | `string` | yes | The username for basic auth |
| `password` | `string` | yes | The password for basic auth |

#### Responses
**200** — Successfully set Inxmail basic auth credentials

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/klaviyo

**Set Klaviyo Key**

Operation ID: `v1.shops.keys.klaviyo.set`

Set a klaviyo api key for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `string` | yes | The api key |

#### Responses
**200** — Successfully set Klaviyo key

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/shopify

**Set Shopify Access Token**

Operation ID: `v1.shops.keys.shopify.set`

Set a shopify access token for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `string` | yes | The api key |

#### Responses
**200** — Successfully set a Shopify access token

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/keys/shopify

**Delete Shopify Access Token**

Operation ID: `v1.shops.keys.shopify.delete`

Delete the shopify access token for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successful Response

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/keys/shopware

**Set Shopware Api Credentials**

Operation ID: `v1.shops.keys.shopware.set`

Set shopware api credentials for the shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | `string` | yes | The client id |
| `client_secret` | `string` | no | The client secret |

#### Responses
**200** — Successfully set Shopware API credentials

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/orders

**Search Orders**

Operation ID: `v1.orders.search`

Search and filter orders for a specific shop.

    This endpoint supports various filters including order status, date ranges,
    customer information, and more. Results are paginated.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `email_id` | `string` | no |  |
| `external_id` | `string` | no |  |
| `order_name` | `string` | no |  |
| `order_number` | `string` | no |  |
| `uuid` | `string` | no |  |
| `zip_code` | `string` | no |  |
| `order_placed_from` | `string` | no |  |
| `order_placed_to` | `string` | no |  |
| `shipment_updated_since` | `string` | no |  |

#### Responses
**200** — List of orders that match the search criteria

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/orders

**Place Order**

Operation ID: `v1.orders.placement`

Create a new order for the shop.

    This endpoint handles order placement from your e-commerce platform.
    The order will be validated, processed, and appropriate shipments will be created.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_number` | `string` | yes | Opinionated numeric identification of the order |
| `order_name` | `string` | no | Opinionated name of the order |
| `order_placed_at` | `string` | no | Date the order was placed. Will take current time if not provided |
| `total_order_price` | `number` | no | Total price of the order |
| `shipping_price` | `number` | no | Total shipping price of the order |
| `sub_total_price` | `number` | no | Subtotal price of items before shipping and discounts |
| `discount_price` | `number` | no | Total price of all the accumulated discounts |
| `products` | `array<object>` | no | Line items for the order |
| `products[].product_id` | `string` | no | Product ID |
| `products[].variant_id` | `string` | no | Variant ID |
| `products[].title` | `string` | no | Product title |
| `products[].variant_title` | `string` | no | Variant title |
| `products[].quantity` | `integer` | no | Quantity of products |
| `products[].price` | `number` | no | Price of the product |
| `products[].discount_price` | `number` | no | Discounted price of the product |
| `products[].currency` | `string` | no | Currency of the product (ISO 4217) |
| `products[].size` | `string` | no | Size of the product |
| `products[].images` | `array<object>` | no | List of product images |
| `products[].images[].src` | `string` | yes | Source of the image |
| `products[].images[].alt` | `string` | no | Alt of the image |
| `products[].sku` | `string` | no | SKU of the product |
| `products[].weight` | `number` | no | Weight of the product in grams |
| `products[].tax_lines` | `array<object>` | no | List of tax lines |
| `products[].tax_lines[].currency` | `string` | no | Currency of the tax line |
| `products[].tax_lines[].price` | `number` | no | Price of the tax line |
| `products[].tax_lines[].rate` | `number` | no | Rate of the tax line |
| `products[].tax_lines[].title` | `string` | no | Title of the tax line |
| `products[].estimated_ship_date_start` | `string` | no | Estimated ship date start from line item properties |
| `products[].estimated_ship_date_end` | `string` | no | Estimated ship date end from line item properties |
| `products[].requires_shipping` | `boolean` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `products[].bundled_products` | `array<object>` | no | List of bundled products |
| `products[].bundled_products[].product_id` | `string` | no | Product ID |
| `products[].bundled_products[].variant_id` | `string` | no | Variant ID |
| `products[].bundled_products[].title` | `string` | no | Product title |
| `products[].bundled_products[].variant_title` | `string` | no | Variant title |
| `products[].bundled_products[].quantity` | `integer` | no | Quantity of products |
| `products[].bundled_products[].price` | `number` | no | Price of the product |
| `products[].bundled_products[].discount_price` | `number` | no | Discounted price of the product |
| `products[].bundled_products[].currency` | `string` | no | Currency of the product (ISO 4217) |
| `products[].bundled_products[].size` | `string` | no | Size of the product |
| `products[].bundled_products[].images` | `array<object>` | no | List of product images |
| `products[].bundled_products[].sku` | `string` | no | SKU of the product |
| `products[].bundled_products[].weight` | `number` | no | Weight of the product in grams |
| `products[].bundled_products[].tax_lines` | `array<object>` | no | List of tax lines |
| `products[].bundled_products[].estimated_ship_date_start` | `string` | no | Estimated ship date start from line item properties |
| `products[].bundled_products[].estimated_ship_date_end` | `string` | no | Estimated ship date end from line item properties |
| `products[].bundled_products[].requires_shipping` | `boolean` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `products[].translations` | `object` | no | Translations by language code |
| `products[].shipment_id` | `string` | no | UUID of the shipment this product belongs to |
| `products[].type` | `"product" \| "bundle"` | no | Product Type. |
| `discounts` | `array<object>` | no | Discounts applied to the order |
| `discounts[].code` | `string` | yes | Code of the discount |
| `discounts[].amount` | `string` | no | Amount of the discount |
| `discounts[].type` | `string` | no | Type of the discount |
| `email_id` | `string` | no | Email address of the customer |
| `address` | `object` | yes | DTO for standardized address objects enforcing that a zip code always exists. |
| `address.address_line_1` | `string` | no | The resident's mailing address |
| `address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `address.city` | `string` | no | The resident's city |
| `address.country` | `string` | no | The resident's country |
| `address.country_code` | `string` | no | The two letter digit resident's country code |
| `address.name` | `string` | no | The first and last names of the resident |
| `address.phone` | `string` | no | The resident's phone number |
| `address.province` | `string` | no | The resident's province or state name |
| `address.province_code` | `string` | no | The resident's province or state name |
| `address.street` | `string` | no | A combination of the first and second lines of the address |
| `address.zip_code` | `string` | yes | The address zip or postal code |
| `address.company` | `string` | no | The company recipient |
| `currency` | `string` | no | ISO 4217 currency code (default to 'EUR') |
| `segments` | `array<string>` | no | The segments to which the user of the order belongs |
| `weight` | `number` | no | Total weight of the order in grams |
| `external_customer_id` | `string` | no | External ID of the customer who purchased the order |
| `order_status_url` | `string` | no | URL to the order status page as given by the shop provider |
| `external_id` | `string` | no | External identifier of the order as defined by the merchant shop system (e.g. shopify's order id). If not provided or empty, defaults to order_number. |
| `preferred_delivery_date` | `object` | no | Schema for a preferred delivery date. |
| `preferred_delivery_date.start` | `string` | no | Preferred Delivery Date From |
| `preferred_delivery_date.end` | `string` | no | Preferred Delivery Date To |
| `preferred_delivery_date.updated_at` | `string` | no | Preferred Delivery Date last updated time |
| `preferred_delivery_date.source` | `string` | no | Preferred Delivery Date source |
| `user_agent` | `string` | no | User agent of the customer |
| `order_analytics` | `object` | no | Analytics information related to the order. This information is not used for any computation, but can be used to track the order in the merchant's analytics system. |
| `expected_number_of_shipments` | `integer` | no | Expected number of shipments for the order (defaults to 1) |
| `financial_status` | `"authorized" \| "paid" \| "partially_paid" \| "partially_refunded" \| "pending" \| "refunded" \| "voided"` | no | Order Financial Status from Shopify. Represents the payment/refund state of an order. |

#### Responses
**200** — Successfully placed an order

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — Order with unique id already exists

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/orders

**Upsert Order**

Operation ID: `v1.orders.upsert`

Process a shop order upsert.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | Order reference whose type is defined by the id_type field |
| `id_type` | `"uuid" \| "external_id" \| "order_number" \| "order_name"` | no | Enum for order reference types. |
| `order` | `object` | no | Representation of an order as sent by a merchant at checkout stage. |
| `order.order_number` | `string` | yes | Opinionated numeric identification of the order |
| `order.order_name` | `string` | no | Opinionated name of the order |
| `order.order_placed_at` | `string` | no | Date the order was placed. Will take current time if not provided |
| `order.total_order_price` | `number` | no | Total price of the order |
| `order.shipping_price` | `number` | no | Total shipping price of the order |
| `order.sub_total_price` | `number` | no | Subtotal price of items before shipping and discounts |
| `order.discount_price` | `number` | no | Total price of all the accumulated discounts |
| `order.products` | `array<object>` | no | Line items for the order |
| `order.products[].product_id` | `string` | no | Product ID |
| `order.products[].variant_id` | `string` | no | Variant ID |
| `order.products[].title` | `string` | no | Product title |
| `order.products[].variant_title` | `string` | no | Variant title |
| `order.products[].quantity` | `integer` | no | Quantity of products |
| `order.products[].price` | `number` | no | Price of the product |
| `order.products[].discount_price` | `number` | no | Discounted price of the product |
| `order.products[].currency` | `string` | no | Currency of the product (ISO 4217) |
| `order.products[].size` | `string` | no | Size of the product |
| `order.products[].images` | `array<object>` | no | List of product images |
| `order.products[].images[].src` | `string` | yes | Source of the image |
| `order.products[].images[].alt` | `string` | no | Alt of the image |
| `order.products[].sku` | `string` | no | SKU of the product |
| `order.products[].weight` | `number` | no | Weight of the product in grams |
| `order.products[].tax_lines` | `array<object>` | no | List of tax lines |
| `order.products[].tax_lines[].currency` | `string` | no | Currency of the tax line |
| `order.products[].tax_lines[].price` | `number` | no | Price of the tax line |
| `order.products[].tax_lines[].rate` | `number` | no | Rate of the tax line |
| `order.products[].tax_lines[].title` | `string` | no | Title of the tax line |
| `order.products[].estimated_ship_date_start` | `string` | no | Estimated ship date start from line item properties |
| `order.products[].estimated_ship_date_end` | `string` | no | Estimated ship date end from line item properties |
| `order.products[].requires_shipping` | `boolean` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `order.products[].bundled_products` | `array<object>` | no | List of bundled products |
| `order.products[].bundled_products[].product_id` | `string` | no | Product ID |
| `order.products[].bundled_products[].variant_id` | `string` | no | Variant ID |
| `order.products[].bundled_products[].title` | `string` | no | Product title |
| `order.products[].bundled_products[].variant_title` | `string` | no | Variant title |
| `order.products[].bundled_products[].quantity` | `integer` | no | Quantity of products |
| `order.products[].bundled_products[].price` | `number` | no | Price of the product |
| `order.products[].bundled_products[].discount_price` | `number` | no | Discounted price of the product |
| `order.products[].bundled_products[].currency` | `string` | no | Currency of the product (ISO 4217) |
| `order.products[].bundled_products[].size` | `string` | no | Size of the product |
| `order.products[].bundled_products[].images` | `array<object>` | no | List of product images |
| `order.products[].bundled_products[].sku` | `string` | no | SKU of the product |
| `order.products[].bundled_products[].weight` | `number` | no | Weight of the product in grams |
| `order.products[].bundled_products[].tax_lines` | `array<object>` | no | List of tax lines |
| `order.products[].bundled_products[].estimated_ship_date_start` | `string` | no | Estimated ship date start from line item properties |
| `order.products[].bundled_products[].estimated_ship_date_end` | `string` | no | Estimated ship date end from line item properties |
| `order.products[].bundled_products[].requires_shipping` | `boolean` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `order.products[].translations` | `object` | no | Translations by language code |
| `order.products[].shipment_id` | `string` | no | UUID of the shipment this product belongs to |
| `order.products[].type` | `"product" \| "bundle"` | no | Product Type. |
| `order.discounts` | `array<object>` | no | Discounts applied to the order |
| `order.discounts[].code` | `string` | yes | Code of the discount |
| `order.discounts[].amount` | `string` | no | Amount of the discount |
| `order.discounts[].type` | `string` | no | Type of the discount |
| `order.email_id` | `string` | no | Email address of the customer |
| `order.address` | `object` | yes | DTO for standardized address objects enforcing that a zip code always exists. |
| `order.address.address_line_1` | `string` | no | The resident's mailing address |
| `order.address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `order.address.city` | `string` | no | The resident's city |
| `order.address.country` | `string` | no | The resident's country |
| `order.address.country_code` | `string` | no | The two letter digit resident's country code |
| `order.address.name` | `string` | no | The first and last names of the resident |
| `order.address.phone` | `string` | no | The resident's phone number |
| `order.address.province` | `string` | no | The resident's province or state name |
| `order.address.province_code` | `string` | no | The resident's province or state name |
| `order.address.street` | `string` | no | A combination of the first and second lines of the address |
| `order.address.zip_code` | `string` | yes | The address zip or postal code |
| `order.address.company` | `string` | no | The company recipient |
| `order.currency` | `string` | no | ISO 4217 currency code (default to 'EUR') |
| `order.segments` | `array<string>` | no | The segments to which the user of the order belongs |
| `order.weight` | `number` | no | Total weight of the order in grams |
| `order.external_customer_id` | `string` | no | External ID of the customer who purchased the order |
| `order.order_status_url` | `string` | no | URL to the order status page as given by the shop provider |
| `order.external_id` | `string` | no | External identifier of the order as defined by the merchant shop system (e.g. shopify's order id). If not provided or empty, defaults to order_number. |
| `order.preferred_delivery_date` | `object` | no | Schema for a preferred delivery date. |
| `order.preferred_delivery_date.start` | `string` | no | Preferred Delivery Date From |
| `order.preferred_delivery_date.end` | `string` | no | Preferred Delivery Date To |
| `order.preferred_delivery_date.updated_at` | `string` | no | Preferred Delivery Date last updated time |
| `order.preferred_delivery_date.source` | `string` | no | Preferred Delivery Date source |
| `order.user_agent` | `string` | no | User agent of the customer |
| `order.order_analytics` | `object` | no | Analytics information related to the order. This information is not used for any computation, but can be used to track the order in the merchant's analytics system. |
| `order.expected_number_of_shipments` | `integer` | no | Expected number of shipments for the order (defaults to 1) |
| `order.financial_status` | `"authorized" \| "paid" \| "partially_paid" \| "partially_refunded" \| "pending" \| "refunded" \| "voided"` | no | Order Financial Status from Shopify. Represents the payment/refund state of an order. |
| `trackings` | `array<object>` | yes | Tracking information relevant to the order (order must exist already if it is not provided) |
| `trackings[].tracking_number` | `string` | yes | Tracking code(s), comma or semicolon separated |
| `trackings[].tracking_url` | `string` | no | The tracking URL as it comes from the carrier. |
| `trackings[].tracking_placed_at` | `string` | no | Date the fulfillment was placed. Will take current time if not provided |
| `trackings[].carrier_reference` | `string` | no | Carrier reference must be a valid karla carrier list value. |
| `trackings[].external_shipment_id` | `string` | no | External shipment ID (for instance, shopify's fulfillment id) |
| `trackings[].origin_full_address` | `object` | no | Schema for standardized address objects. |
| `trackings[].origin_full_address.address_line_1` | `string` | no | The resident's mailing address |
| `trackings[].origin_full_address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `trackings[].origin_full_address.city` | `string` | no | The resident's city |
| `trackings[].origin_full_address.country` | `string` | no | The resident's country |
| `trackings[].origin_full_address.country_code` | `string` | no | The two letter digit resident's country code |
| `trackings[].origin_full_address.name` | `string` | no | The first and last names of the resident |
| `trackings[].origin_full_address.phone` | `string` | no | The resident's phone number |
| `trackings[].origin_full_address.province` | `string` | no | The resident's province or state name |
| `trackings[].origin_full_address.province_code` | `string` | no | The resident's province or state name |
| `trackings[].origin_full_address.street` | `string` | no | A combination of the first and second lines of the address |
| `trackings[].origin_full_address.zip_code` | `string` | no | The address zip or postal code |
| `trackings[].external_origin_id` | `string` | no | External origin identifier (e.g., Shopify location_id) |
| `trackings[].products` | `array<object>` | no | Line items involved in the delivery. If not provided, all products from the related order will be considered as delivered. |
| `trackings[].tracking_company` | `string` | no | External Tracking Company Name - can be any string that identifies the carrier. |

#### Responses
**200** — Successfully created or updated a single order

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Order not found when trying to update (no order provided)

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/orders/analytics

**Upsert Order Analytics**

Operation ID: `v1.orders.analytics.upsert`

Upsert Karla tracking analytics data for an order.

    Uses PUT semantics: all Karla tracking fields (source, campaign, medium,
    landing_url, landing_path, referrer, captured_at, reference_order_id) are
    **fully overwritten** on every call, including with null values.
    Non-Karla fields (e.g. landing_site, note_attributes from Shopify)
    are preserved.

    This means values previously set via Shopify note_attributes or the
    PUT orders endpoint will be overwritten if not included in the payload.

    The order can be identified by UUID, order number, or external ID
    using the id and id_type fields in the request body.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | `string` | no | Traffic source identifier |
| `campaign` | `string` | no | Campaign identifier (typically a UUID) |
| `medium` | `string` | no | Marketing medium (e.g., basic_promotion, product_promotion) |
| `landing_url` | `string` | no | Full landing URL including query parameters |
| `landing_path` | `string` | no | Landing page path without domain |
| `referrer` | `string` | no | Referrer URL |
| `captured_at` | `string` | no | Timestamp when the tracking data was captured |
| `reference_order_id` | `string` | no | Reference to an original or parent order (e.g., for linking upsell orders to their source order) |
| `order_external_id` | `string` | no | External ID of the source order that drove this conversion |
| `order_number` | `string` | no | Order number of the source order that drove this conversion |
| `order_name` | `string` | no | Display name of the source order that drove this conversion |
| `id` | `string` | yes | Order reference whose type is defined by the id_type field |
| `id_type` | `"uuid" \| "external_id" \| "order_number" \| "order_name"` | no | Enum for order reference types. |

#### Responses
**200** — Successfully upserted order analytics

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Shop or order not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/orders/bulk

**Fulfill Orders**

Operation ID: `v1.orders.fulfillment.bulk`

Process a shop order fulfillment in bulk (via shop slug).

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
_No documented body fields._

#### Responses
**200** — Successfully processed order fulfillments operation

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/orders/{order_identifier}/shipments/{tracking_number}

**Delete Shipment from Order**

Operation ID: `v1.orders.shipments.delete`

Delete a shipment from an order by tracking number.

    The order can be identified by UUID, order number, or external ID.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `order_identifier` | `string` | yes | The order identifier (UUID, order number, or external ID) |
| `tracking_number` | `string` | yes | The tracking number of the shipment to delete |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted shipment

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find order or shipment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/orders/{order_id}

**Update Order**

Operation ID: `v1.orders.update`

Process a shop order update.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `order_id` | `string` | yes | The id given by Karla identifying the order |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | `object` | no | DTO for standardized address objects. |
| `address.address_line_1` | `string` | no | The resident's mailing address |
| `address.address_line_2` | `string` | no | An additional field for the customer's mailing address |
| `address.city` | `string` | no | The resident's city |
| `address.country` | `string` | no | The resident's country |
| `address.country_code` | `string` | no | The two letter digit resident's country code |
| `address.name` | `string` | no | The first and last names of the resident |
| `address.phone` | `string` | no | The resident's phone number |
| `address.province` | `string` | no | The resident's province or state name |
| `address.province_code` | `string` | no | The resident's province or state name |
| `address.street` | `string` | no | A combination of the first and second lines of the address |
| `address.zip_code` | `string` | no | The address zip or postal code |
| `address.company` | `string` | no | The company recipient |
| `expected_number_of_shipments` | `integer` | no | Expected number of shipments for the order (skips update if undefined). |
| `segments` | `array<string>` | no | Segments to assign to the order, replacing any existing segments (skips update if undefined). |

#### Responses
**200** — Successfully updated an order

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_number` | `string` | yes | Opinionated numeric identification of the order |
| `order_name` | `string` | no | Opinionated name of the order |
| `order_placed_at` | `string` | no | Date the order was placed. Will take current time if not provided |
| `total_order_price` | `number` | no | Total price of the order |
| `shipping_price` | `number` | no | Total shipping price of the order |
| `sub_total_price` | `number` | no | Subtotal price of items before shipping and discounts |
| `discount_price` | `number` | no | Total price of all the accumulated discounts |
| `products` | `array<object>` | no | Line items for the order |
| `products[].product_id` | `any` | no | Product ID |
| `products[].variant_id` | `any` | no | Variant ID |
| `products[].title` | `any` | no | Product title |
| `products[].variant_title` | `any` | no | Variant title |
| `products[].quantity` | `any` | no | Quantity of products |
| `products[].price` | `any` | no | Price of the product |
| `products[].discount_price` | `any` | no | Discounted price of the product |
| `products[].currency` | `any` | no | Currency of the product (ISO 4217) |
| `products[].size` | `any` | no | Size of the product |
| `products[].images` | `any` | no | List of product images |
| `products[].sku` | `any` | no | SKU of the product |
| `products[].weight` | `any` | no | Weight of the product in grams |
| `products[].tax_lines` | `any` | no | List of tax lines |
| `products[].estimated_ship_date_start` | `any` | no | Estimated ship date start from line item properties |
| `products[].estimated_ship_date_end` | `any` | no | Estimated ship date end from line item properties |
| `products[].requires_shipping` | `any` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `products[].bundled_products` | `any` | no | List of bundled products |
| `products[].translations` | `any` | no | Translations by language code |
| `products[].shipment_id` | `any` | no | UUID of the shipment this product belongs to |
| `products[].type` | `any` | no | The type of the product (individual or bundle) |
| `discounts` | `array<object>` | no | Discounts applied to the order |
| `discounts[].code` | `any` | yes | Code of the discount |
| `discounts[].amount` | `any` | no | Amount of the discount |
| `discounts[].type` | `any` | no | Type of the discount |
| `email_id` | `string` | no | Email address of the customer |
| `address` | `object` | yes | DTO for standardized address objects. |
| `address.address_line_1` | `any` | no | The resident's mailing address |
| `address.address_line_2` | `any` | no | An additional field for the customer's mailing address |
| `address.city` | `any` | no | The resident's city |
| `address.country` | `any` | no | The resident's country |
| `address.country_code` | `any` | no | The two letter digit resident's country code |
| `address.name` | `any` | no | The first and last names of the resident |
| `address.phone` | `any` | no | The resident's phone number |
| `address.province` | `any` | no | The resident's province or state name |
| `address.province_code` | `any` | no | The resident's province or state name |
| `address.street` | `any` | no | A combination of the first and second lines of the address |
| `address.zip_code` | `any` | no | The address zip or postal code |
| `address.company` | `any` | no | The company recipient |
| `currency` | `string` | no | ISO 4217 currency code (default to 'EUR') |
| `segments` | `array<string>` | no | The segments to which the user of the order belongs |
| `weight` | `number` | no | Total weight of the order in grams |
| `external_customer_id` | `string` | no | External ID of the customer who purchased the order |
| `order_status_url` | `string` | no | URL to the order status page as given by the shop provider |
| `uuid` | `string` | yes | Unique identifier for the order |
| `external_id` | `string` | yes | External identifier of the order as defined by the merchant shop system (e.g. shopify's order id) |
| `shop_slug` | `string` | yes | Shop slug identifier |
| `merchant_slug` | `string` | no | Merchant slug identifier (DEPRECATED - use shop_slug) |
| `order_analytics` | `object` | no | Order analytics data returned in order responses. |
| `order_analytics.source` | `string` | no | Traffic source identifier |
| `order_analytics.campaign` | `string` | no | Campaign identifier (typically a UUID) |
| `order_analytics.medium` | `string` | no | Marketing medium (e.g., basic_promotion, product_promotion) |
| `order_analytics.landing_url` | `string` | no | Full landing URL including query parameters |
| `order_analytics.landing_path` | `string` | no | Landing page path without domain |
| `order_analytics.referrer` | `string` | no | Referrer URL |
| `order_analytics.captured_at` | `string` | no | Timestamp when the tracking data was captured |
| `order_analytics.reference_order_id` | `string` | no | Reference to an original or parent order (e.g., for linking upsell orders to their source order) |
| `order_analytics.order_external_id` | `string` | no | External ID of the source order that drove this conversion |
| `order_analytics.order_number` | `string` | no | Order number of the source order that drove this conversion |
| `order_analytics.order_name` | `string` | no | Display name of the source order that drove this conversion |
| `trackings` | `array<object>` | no | The tracking information for the shipment/s involved in the order |
| `trackings[].uuid` | `string \| string` | yes | Shipment UUID |
| `trackings[].updated_at` | `string` | no | Tracking last updated time |
| `trackings[].events` | `array<object>` | yes | Shipment tracking events. See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) |
| `trackings[].events[].event_key` | `any` | yes | Event Key |
| `trackings[].events[].time` | `string` | no | Event Time |
| `trackings[].events[].timezone` | `any` | no | Event Timezone |
| `trackings[].events[].location` | `any` | no | Event Location |
| `trackings[].events[].additional_info` | `any` | no | Event Additional Info |
| `trackings[].events[].phase` | `any` | yes | Phase of the shipment |
| `trackings[].events[].event_name` | `any` | yes | Shipment event name.<br>See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details.<br><details><summary>Possible values</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `trackings[].events[].event_strings` | `any` | no | Event translation strings |
| `trackings[].events[].language` | `any` | yes | The locale of the language for the event |
| `trackings[].estimated_arrival` | `object` | no | Event strings for a specific language as defined in the language files. |
| `trackings[].estimated_arrival.from` | `string` | no | Start date for the ETA range (same as end if a range is not provided) |
| `trackings[].estimated_arrival.to` | `string` | no | Expected Delivery To |
| `trackings[].estimated_arrival.time_prediction` | `string` | yes | Estimated time of arrival for the shipment |
| `trackings[].estimated_arrival.language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | yes | Supported languages. |
| `trackings[].estimated_arrival.source` | `string` | no | Public-facing source of the estimated delivery time. Values: 'carrier' (from shipping carrier), 'AI' (AI prediction), 'custom' (manual/custom entry), 'order' (from order data) |
| `trackings[].carrier` | `object` | no | Carrier DTO to be used in the Tracking object. |
| `trackings[].carrier.tracking_number` | `string` | yes | Carrier Tracking Number |
| `trackings[].carrier.carrier_reference` | `string` | yes | Carrier reference |
| `trackings[].carrier.tracking_url` | `string` | no | Shipment tracking URL. |
| `trackings[].flag` | `"normal" \| "delay" \| "error"` | no | Karla internal shipment flag. Raises the possibility of failure or delay when not normal. Options: normal, delay, error. |
| `trackings[].pickup` | `object` | no | PickUp information for the delivery of a shipment. |
| `trackings[].pickup.type` | `"shop" \| "neighbor" \| "locker" \| "letterbox"` | no | Pickup Type. |
| `trackings[].pickup.name` | `string` | yes | PickUp name |
| `trackings[].pickup.address` | `object` | no | DTO for standardized address objects. |
| `trackings[].pickup.url` | `string` | no | PickUp url |
| `trackings[].pickup.opening_hours` | `string` | no | PickUp opening hours |
| `trackings[].pickup.date_to` | `string` | no | PickUp date to |
| `trackings[].products` | `array<object>` | no | List of shipment products |
| `trackings[].products[].product_id` | `any` | no | Product ID |
| `trackings[].products[].variant_id` | `any` | no | Variant ID |
| `trackings[].products[].title` | `any` | no | Product title |
| `trackings[].products[].variant_title` | `any` | no | Variant title |
| `trackings[].products[].quantity` | `any` | no | Quantity of products |
| `trackings[].products[].price` | `any` | no | Price of the product |
| `trackings[].products[].discount_price` | `any` | no | Discounted price of the product |
| `trackings[].products[].currency` | `any` | no | Currency of the product (ISO 4217) |
| `trackings[].products[].size` | `any` | no | Size of the product |
| `trackings[].products[].images` | `any` | no | List of product images |
| `trackings[].products[].sku` | `any` | no | SKU of the product |
| `trackings[].products[].weight` | `any` | no | Weight of the product in grams |
| `trackings[].products[].tax_lines` | `any` | no | List of tax lines |
| `trackings[].products[].estimated_ship_date_start` | `any` | no | Estimated ship date start from line item properties |
| `trackings[].products[].estimated_ship_date_end` | `any` | no | Estimated ship date end from line item properties |
| `trackings[].products[].requires_shipping` | `any` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `trackings[].products[].bundled_products` | `any` | no | List of bundled products |
| `trackings[].products[].translations` | `any` | no | Translations by language code |
| `trackings[].direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `trackings[].is_return` | `boolean` | no | Indicates whether this is a return shipment |
| `trackings[].id` | `string \| string` | yes | Shipment UUID (DEPRECATED, use uuid instead) |
| `trackings[].merchant_id` | `string \| string` | yes | Merchant UUID (DEPRECATED) |
| `trackings[].merchant_slug` | `string` | yes | Merchant slug identifier (DEPRECATED, use shop_slug instead) |
| `trackings[].shop_slug` | `string` | yes | Shop slug identifier |
| `trackings[].order_id` | `string \| string` | yes | Order identifier within Karla |
| `trackings[].order_number` | `string` | yes | Order number communicated to the user by the Merchant |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/orders/{order_id}/shipments/{shipment_id}

**Update Order Shipment**

Operation ID: `v1.orders.shipments.update`

Process a shop order shipment update.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `order_id` | `string` | yes | The id given by Karla identifying the order |
| `shipment_id` | `string` | yes | The id given by Karla identifying the tracking from the order |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tracking_url` | `string` | no | The tracking URL as it comes from the carrier. |
| `products` | `array<object>` | no | Line items involved in the delivery. Give an empty list to remove all products from the shipment.Any list provided will override the current products in the shipment (there is no merge). Will be skipped from update if not given |
| `products[].product_id` | `string` | no | Product ID |
| `products[].variant_id` | `string` | no | Variant ID |
| `products[].title` | `string` | no | Product title |
| `products[].variant_title` | `string` | no | Variant title |
| `products[].quantity` | `integer` | no | Quantity of products |
| `products[].price` | `number` | no | Price of the product |
| `products[].discount_price` | `number` | no | Discounted price of the product |
| `products[].currency` | `string` | no | Currency of the product (ISO 4217) |
| `products[].size` | `string` | no | Size of the product |
| `products[].images` | `array<object>` | no | List of product images |
| `products[].images[].src` | `string` | yes | Source of the image |
| `products[].images[].alt` | `string` | no | Alt of the image |
| `products[].sku` | `string` | no | SKU of the product |
| `products[].weight` | `number` | no | Weight of the product in grams |
| `products[].tax_lines` | `array<object>` | no | List of tax lines |
| `products[].tax_lines[].currency` | `string` | no | Currency of the tax line |
| `products[].tax_lines[].price` | `number` | no | Price of the tax line |
| `products[].tax_lines[].rate` | `number` | no | Rate of the tax line |
| `products[].tax_lines[].title` | `string` | no | Title of the tax line |
| `products[].estimated_ship_date_start` | `string` | no | Estimated ship date start from line item properties |
| `products[].estimated_ship_date_end` | `string` | no | Estimated ship date end from line item properties |
| `products[].requires_shipping` | `boolean` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `products[].bundled_products` | `array<object>` | no | List of bundled products |
| `products[].bundled_products[].product_id` | `string` | no | Product ID |
| `products[].bundled_products[].variant_id` | `string` | no | Variant ID |
| `products[].bundled_products[].title` | `string` | no | Product title |
| `products[].bundled_products[].variant_title` | `string` | no | Variant title |
| `products[].bundled_products[].quantity` | `integer` | no | Quantity of products |
| `products[].bundled_products[].price` | `number` | no | Price of the product |
| `products[].bundled_products[].discount_price` | `number` | no | Discounted price of the product |
| `products[].bundled_products[].currency` | `string` | no | Currency of the product (ISO 4217) |
| `products[].bundled_products[].size` | `string` | no | Size of the product |
| `products[].bundled_products[].images` | `array<object>` | no | List of product images |
| `products[].bundled_products[].sku` | `string` | no | SKU of the product |
| `products[].bundled_products[].weight` | `number` | no | Weight of the product in grams |
| `products[].bundled_products[].tax_lines` | `array<object>` | no | List of tax lines |
| `products[].bundled_products[].estimated_ship_date_start` | `string` | no | Estimated ship date start from line item properties |
| `products[].bundled_products[].estimated_ship_date_end` | `string` | no | Estimated ship date end from line item properties |
| `products[].bundled_products[].requires_shipping` | `boolean` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `products[].translations` | `object` | no | Translations by language code |
| `products[].shipment_id` | `string` | no | UUID of the shipment this product belongs to |
| `products[].type` | `"product" \| "bundle"` | no | Product Type. |

#### Responses
**200** — Successfully updated an order shipment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string \| string` | yes | Shipment UUID |
| `updated_at` | `string` | no | Tracking last updated time |
| `events` | `array<object>` | yes | Shipment tracking events. See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) |
| `events[].event_key` | `any` | yes | Event Key |
| `events[].time` | `string` | no | Event Time |
| `events[].timezone` | `any` | no | Event Timezone |
| `events[].location` | `any` | no | Event Location |
| `events[].additional_info` | `any` | no | Event Additional Info |
| `events[].phase` | `any` | yes | Phase of the shipment |
| `events[].event_name` | `any` | yes | Shipment event name.<br>See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details.<br><details><summary>Possible values</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `events[].event_strings` | `any` | no | Event translation strings |
| `events[].language` | `any` | yes | The locale of the language for the event |
| `estimated_arrival` | `object` | no | Event strings for a specific language as defined in the language files. |
| `estimated_arrival.from` | `string` | no | Start date for the ETA range (same as end if a range is not provided) |
| `estimated_arrival.to` | `string` | no | Expected Delivery To |
| `estimated_arrival.time_prediction` | `string` | yes | Estimated time of arrival for the shipment |
| `estimated_arrival.language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | yes | Supported languages. |
| `estimated_arrival.source` | `string` | no | Public-facing source of the estimated delivery time. Values: 'carrier' (from shipping carrier), 'AI' (AI prediction), 'custom' (manual/custom entry), 'order' (from order data) |
| `carrier` | `object` | no | Carrier DTO to be used in the Tracking object. |
| `carrier.tracking_number` | `string` | yes | Carrier Tracking Number |
| `carrier.carrier_reference` | `string` | yes | Carrier reference |
| `carrier.tracking_url` | `string` | no | Shipment tracking URL. |
| `flag` | `"normal" \| "delay" \| "error"` | no | Karla internal shipment flag. Raises the possibility of failure or delay when not normal. Options: normal, delay, error. |
| `pickup` | `object` | no | PickUp information for the delivery of a shipment. |
| `pickup.type` | `"shop" \| "neighbor" \| "locker" \| "letterbox"` | no | Pickup Type. |
| `pickup.name` | `string` | yes | PickUp name |
| `pickup.address` | `object` | no | DTO for standardized address objects. |
| `pickup.address.address_line_1` | `any` | no | The resident's mailing address |
| `pickup.address.address_line_2` | `any` | no | An additional field for the customer's mailing address |
| `pickup.address.city` | `any` | no | The resident's city |
| `pickup.address.country` | `any` | no | The resident's country |
| `pickup.address.country_code` | `any` | no | The two letter digit resident's country code |
| `pickup.address.name` | `any` | no | The first and last names of the resident |
| `pickup.address.phone` | `any` | no | The resident's phone number |
| `pickup.address.province` | `any` | no | The resident's province or state name |
| `pickup.address.province_code` | `any` | no | The resident's province or state name |
| `pickup.address.street` | `any` | no | A combination of the first and second lines of the address |
| `pickup.address.zip_code` | `any` | no | The address zip or postal code |
| `pickup.address.company` | `any` | no | The company recipient |
| `pickup.url` | `string` | no | PickUp url |
| `pickup.opening_hours` | `string` | no | PickUp opening hours |
| `pickup.date_to` | `string` | no | PickUp date to |
| `products` | `array<object>` | no | List of shipment products |
| `products[].product_id` | `any` | no | Product ID |
| `products[].variant_id` | `any` | no | Variant ID |
| `products[].title` | `any` | no | Product title |
| `products[].variant_title` | `any` | no | Variant title |
| `products[].quantity` | `any` | no | Quantity of products |
| `products[].price` | `any` | no | Price of the product |
| `products[].discount_price` | `any` | no | Discounted price of the product |
| `products[].currency` | `any` | no | Currency of the product (ISO 4217) |
| `products[].size` | `any` | no | Size of the product |
| `products[].images` | `any` | no | List of product images |
| `products[].sku` | `any` | no | SKU of the product |
| `products[].weight` | `any` | no | Weight of the product in grams |
| `products[].tax_lines` | `any` | no | List of tax lines |
| `products[].estimated_ship_date_start` | `any` | no | Estimated ship date start from line item properties |
| `products[].estimated_ship_date_end` | `any` | no | Estimated ship date end from line item properties |
| `products[].requires_shipping` | `any` | no | Whether this product requires physical shipping. False for digital products, gift cards, services, etc. |
| `products[].bundled_products` | `any` | no | List of bundled products |
| `products[].translations` | `any` | no | Translations by language code |
| `direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `is_return` | `boolean` | no | Indicates whether this is a return shipment |
| `id` | `string \| string` | yes | Shipment UUID (DEPRECATED, use uuid instead) |
| `merchant_id` | `string \| string` | yes | Merchant UUID (DEPRECATED) |
| `merchant_slug` | `string` | yes | Merchant slug identifier (DEPRECATED, use shop_slug instead) |
| `shop_slug` | `string` | yes | Shop slug identifier |
| `order_id` | `string \| string` | yes | Order identifier within Karla |
| `order_number` | `string` | yes | Order number communicated to the user by the Merchant |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/products

**List Shop Products**

Operation ID: `v1.shops.products.list`

List all product variants for a shop with pagination.

    Returns a simple list of products.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `title` | `string` | no |  |
| `product_id` | `string` | no |  |
| `sku` | `string` | no |  |

#### Responses
**200** — Products retrieved successfully

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/products

**Bulk Upsert Product Variants**

Operation ID: `v1.products.bulk_upsert`

Create or update multiple product variants in bulk.

    This endpoint accepts a list of product variants and upserts them.
    If a variant already exists (matched by product_id + variant_id),
    it will be updated. Otherwise, a new variant will be created.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
_No documented body fields._

#### Responses
**200** — Product variants upserted successfully

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/products/{product_id}

**Delete Product and All Variants**

Operation ID: `v1.products.delete_product`

Delete a product and all its variants by product ID.

    This is a cascade delete operation that removes the parent product
    and all associated variants.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `product_id` | `string` | yes | Product ID from the shop provider |

#### Responses
**200** — Successfully processed operation

**204** — Product deleted successfully

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/products/{product_id}/recommendations

**Get Product Recommendations**

Operation ID: `v1.shops.products.recommendations`

Get product recommendations for a specific product.

    This endpoint returns recommended products based on the given product ID.
    The recommendations are retrieved from the shop provider (e.g., Shopify).

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `product_id` | `string` | yes | The ID of the product to get recommendations for |

#### Responses
**200** — Product recommendations retrieved successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `products` | `array<object>` | no |  |
| `products[].id` | `integer` | yes | Product ID |
| `products[].title` | `string` | yes | Product title |
| `products[].handle` | `string` | yes | Product handle |
| `products[].price` | `integer` | yes | Product price |
| `products[].price_min` | `integer` | yes | Minimum price |
| `products[].price_max` | `integer` | yes | Maximum price |
| `products[].url` | `string` | yes | Product URL |
| `products[].featured_image` | `string` | no |  |
| `products[].variants` | `array<object>` | no |  |
| `products[].variants[].id` | `integer` | yes | Variant ID |
| `products[].variants[].title` | `string` | yes | Variant title |
| `products[].variants[].price` | `integer` | yes | Variant price |
| `products[].variants[].available` | `boolean` | yes | Variant availability |
| `products[].images` | `array<string>` | no |  |
| `products[].media` | `array<object>` | no |  |
| `products[].media[].id` | `integer` | yes | Image ID |
| `products[].media[].src` | `string` | no | Image URL |
| `products[].media[].alt` | `string` | no | Image alt text |
| `products[].media[].width` | `integer` | no | Image width |
| `products[].media[].height` | `integer` | no | Image height |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/products/{product_id}/variants/{variant_id}

**Get Product Variant**

Operation ID: `v1.products.get_variant`

Get a single product variant by its product ID and variant ID.

    Both IDs come from your shop provider (Shopify, Shopware, etc.).

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `product_id` | `string` | yes | Product ID from the shop provider |
| `variant_id` | `string` | yes | Variant ID from the shop provider |

#### Responses
**200** — Product variant retrieved successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | Shop product UUID |
| `shop_slug` | `string` | yes | Shop slug |
| `shop_provider` | `"shopware" \| "shopify" \| "woocommerce" \| "api"` | yes | Enum for identifying the shop provider of a merchant. |
| `product_id` | `string` | yes | Product ID |
| `variant_id` | `string` | yes | Variant ID |
| `title` | `string` | yes | Product title |
| `variant_title` | `string` | no | Variant title |
| `price` | `number` | no | Variant price |
| `image_url` | `string` | no | Variant image URL |
| `sku` | `string` | no | Variant SKU |
| `product_url` | `string` | no | Product URL |
| `translations` | `object` | no | Translations by language code |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop or variant

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/products/{product_id}/variants/{variant_id}

**Upsert Product Variant**

Operation ID: `v1.products.upsert_variant`

Create or update a single product variant.

    This endpoint uses PUT semantics: it will create the variant if it doesn't exist,
    or replace it entirely if it does. This operation is idempotent.

    The product_id and variant_id are provided in the URL path,
    not in the request body, following RESTful design principles.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `product_id` | `string` | yes | Product ID from the shop provider |
| `variant_id` | `string` | yes | Variant ID from the shop provider |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | yes | Product title |
| `variant_title` | `string` | no | Variant title |
| `price` | `number` | no | Variant price |
| `image_url` | `string` | no | Variant image URL |
| `sku` | `string` | no | Variant SKU |
| `product_url` | `string` | no | Product URL |

#### Responses
**200** — Product variant upserted successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | Shop product UUID |
| `shop_slug` | `string` | yes | Shop slug |
| `shop_provider` | `"shopware" \| "shopify" \| "woocommerce" \| "api"` | yes | Enum for identifying the shop provider of a merchant. |
| `product_id` | `string` | yes | Product ID |
| `variant_id` | `string` | yes | Variant ID |
| `title` | `string` | yes | Product title |
| `variant_title` | `string` | no | Variant title |
| `price` | `number` | no | Variant price |
| `image_url` | `string` | no | Variant image URL |
| `sku` | `string` | no | Variant SKU |
| `product_url` | `string` | no | Product URL |
| `translations` | `object` | no | Translations by language code |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/products/{product_id}/variants/{variant_id}

**Delete Product Variant**

Operation ID: `v1.products.delete_variant`

Delete a single product variant.

    This deletes only the specific variant, not the entire product or other variants.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `product_id` | `string` | yes | Product ID from the shop provider |
| `variant_id` | `string` | yes | Variant ID from the shop provider |

#### Responses
**200** — Successfully processed operation

**204** — Product variant deleted successfully

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings

**Get Shop Settings**

Operation ID: `v1.shops.settings.get`

Get settings for a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved shop settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `carriers` | `object` | yes | The trigger settings object to be exchanged with the HTTP clients. |
| `carriers.shipment_updates` | `boolean` | yes | Shipment updates from carriers retrieval status |
| `triggers` | `object` | yes | The trigger settings object to be exchanged with the HTTP clients. |
| `triggers.klaviyo` | `boolean` | yes | Karla to Klaviyo triggers status |
| `triggers.shopify` | `boolean` | yes | Karla to Shopify triggers status |
| `triggers.emarsys` | `boolean` | yes | Karla to Emarsys triggers status |
| `triggers.brevo` | `boolean` | yes | Karla to Brevo triggers status |
| `triggers.inxmail` | `boolean` | yes | Karla to Inxmail triggers status |
| `triggers.braze` | `boolean` | yes | Karla to Braze triggers status |
| `triggers.hubspot` | `boolean` | yes | Karla to HubSpot triggers status |
| `segments` | `object` | yes | The segment settings object to be exchanged with the HTTP clients. |
| `segments.klaviyo` | `boolean` | yes | Klaviyo segment retrieval status |
| `segments.shopify` | `boolean` | no | Shopify segment retrieval status |
| `segments.emarsys` | `boolean` | yes | Emarsys segment retrieval status |
| `segments.brevo` | `boolean` | yes | Brevo segment retrieval status |
| `segments.inxmail` | `boolean` | yes | Inxmail segment retrieval status |
| `segments.braze` | `boolean` | yes | Braze segment retrieval status |
| `segments.hubspot` | `boolean` | yes | HubSpot segment retrieval status |
| `brand_palette` | `object` | yes | Brand palette colors. |
| `brand_palette.primary_dark` | `string` | yes | Primary dark color |
| `brand_palette.primary_light` | `string` | yes | Primary light color |
| `brand_palette.secondary_dark` | `string` | yes | Secondary dark color |
| `brand_palette.secondary_light` | `string` | yes | Secondary light color |
| `brand_palette.background` | `string` | yes | Background color |
| `brand_palette.surface` | `string` | yes | Surface color |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/brand-palette/colors

**Get Brand Palette Colors**

Operation ID: `v1.shops.settings.brand_palette.colors.get`

Get brand palette colors for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved brand palette colors

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primary_dark` | `string` | yes | Primary dark color |
| `primary_light` | `string` | yes | Primary light color |
| `secondary_dark` | `string` | yes | Secondary dark color |
| `secondary_light` | `string` | yes | Secondary light color |
| `background` | `string` | yes | Background color |
| `surface` | `string` | yes | Surface color |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/brand-palette/colors

**Update Brand Palette Colors**

Operation ID: `v1.shops.settings.brand_palette.colors.update`

Update brand palette colors for a shop.

Allows partial updates - only provided color fields will be updated.
Example: { "primary_dark": "#FF0000" } updates only primary_dark.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primary_dark` | `string` | no | Primary dark color |
| `primary_light` | `string` | no | Primary light color |
| `secondary_dark` | `string` | no | Secondary dark color |
| `secondary_light` | `string` | no | Secondary light color |
| `background` | `string` | no | Background color |
| `surface` | `string` | no | Surface color |

#### Responses
**200** — Successfully updated brand palette colors

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `primary_dark` | `string` | yes | Primary dark color |
| `primary_light` | `string` | yes | Primary light color |
| `secondary_dark` | `string` | yes | Secondary dark color |
| `secondary_light` | `string` | yes | Secondary light color |
| `background` | `string` | yes | Background color |
| `surface` | `string` | yes | Surface color |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/campaigns

**Update Shop Campaigns Settings**

Operation ID: `v1.shops.settings.campaigns.update`

Update campaign settings for a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_recommendations_enabled` | `boolean` | no | Toggle dynamic campaigns |

#### Responses
**200** — Successfully updated campaigns settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_recommendations_enabled` | `boolean` | yes | Dynamic campaigns status |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/carriers

**Update Shop Carrier Settings**

Operation ID: `v1.shops.settings.carriers.update`

Update carrier settings for a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipment_updates` | `boolean` | no | Toggle retrieving shipment updates from carriers |

#### Responses
**200** — Successfully updated carrier settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipment_updates` | `boolean` | yes | Shipment updates from carriers retrieval status |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/mappings

**Get Shop Mappings**

Operation ID: `v1.shops.settings.mappings.get`

Get mappings settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved mappings settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `integer` | no | Version of the mappings schema |
| `data` | `object` | no | Mapping rules grouped by context scope. |
| `data.shopify.order` | `array<object>` | no | Mapping rules for Shopify order context |
| `data.shopify.order[].source` | `object` | yes | Source field definition for a mapping rule. Three source types are supported: **note_attribute** — extracts a value from Shopify order note_attributes by matching on the attribute name (key). Example: ``{"type": "note_attribute", "key": "Zalando Kundennummer"}`` extracts the value of the note attribute named "Zalando Kundennummer". **note** — extracts a value from the Shopify order note (free-text) using a regex pattern with capture groups. The first match is used. Example: ``{"type": "note", "pattern": "Return tracking codes:\s*(\S+)"}`` extracts ``00341234567530088154`` from a note containing ``"Return tracking codes: 00341234567530088154"``. **line_item_property** — extracts a value from a Shopify line item property by matching on the property name (key). Example: ``{"type": "line_item_property", "key": "ETA_start"}`` extracts the value of the line item property named "ETA_start". For the **note** source type, most standard regex features are supported, including: ``\d``, ``\s``, ``\S``, ``\w``, ``\b``, ``[a-z]``, ``a+``, ``a*``, ``a?``, ``a{2,5}``, ``(?:...)``, ``(?P<name>...)``, ``(?i)`` (case-insensitive flag). |
| `data.shopify.order[].source.type` | `"note_attribute" \| "note" \| "line_item_property"` | yes | Valid source types for mapping rules. - note_attribute: Extract value from a Shopify note_attribute by key. - note: Extract value from the Shopify order note using a regex pattern. - line_item_property: Extract value from a Shopify line item property by key. |
| `data.shopify.order[].source.key` | `string` | no | Property or attribute name to match. Required for note_attribute and line_item_property, not allowed for note. Example: 'Zalando Kundennummer' or 'ETA_start' |
| `data.shopify.order[].source.pattern` | `string` | no | Regex pattern with at least one capture group. Required for note, not allowed for note_attribute. The first match in the note text is used. Example: 'Return tracking codes:\s*(\S+)' |
| `data.shopify.order[].source.group` | `integer` | no | Which capture group to extract (1-indexed). Only used with note source type. Example: pattern '(carrier):\s*(\S+)' with group=2 extracts the value after 'carrier:'. |
| `data.shopify.order[].target` | `"return_tracking_number" \| "return_carrier_reference" \| "marketplace_order_number" \| "estimated_ship_date_start" \| "estimated_ship_date_end"` | yes | Valid target fields for mapping rules. |
| `data.shopify.line_item` | `array<object>` | no | Mapping rules for Shopify line item context |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/mappings

**Set Shop Mappings**

Operation ID: `v1.shops.settings.mappings.set`

Set mappings settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `integer` | no | Version of the mappings schema |
| `data` | `object` | no | Mapping rules grouped by context scope. |
| `data.shopify.order` | `array<object>` | no | Mapping rules for Shopify order context |
| `data.shopify.order[].source` | `object` | yes | Source field definition for a mapping rule. Three source types are supported: **note_attribute** — extracts a value from Shopify order note_attributes by matching on the attribute name (key). Example: ``{"type": "note_attribute", "key": "Zalando Kundennummer"}`` extracts the value of the note attribute named "Zalando Kundennummer". **note** — extracts a value from the Shopify order note (free-text) using a regex pattern with capture groups. The first match is used. Example: ``{"type": "note", "pattern": "Return tracking codes:\s*(\S+)"}`` extracts ``00341234567530088154`` from a note containing ``"Return tracking codes: 00341234567530088154"``. **line_item_property** — extracts a value from a Shopify line item property by matching on the property name (key). Example: ``{"type": "line_item_property", "key": "ETA_start"}`` extracts the value of the line item property named "ETA_start". For the **note** source type, most standard regex features are supported, including: ``\d``, ``\s``, ``\S``, ``\w``, ``\b``, ``[a-z]``, ``a+``, ``a*``, ``a?``, ``a{2,5}``, ``(?:...)``, ``(?P<name>...)``, ``(?i)`` (case-insensitive flag). |
| `data.shopify.order[].source.type` | `"note_attribute" \| "note" \| "line_item_property"` | yes | Valid source types for mapping rules. - note_attribute: Extract value from a Shopify note_attribute by key. - note: Extract value from the Shopify order note using a regex pattern. - line_item_property: Extract value from a Shopify line item property by key. |
| `data.shopify.order[].source.key` | `string` | no | Property or attribute name to match. Required for note_attribute and line_item_property, not allowed for note. Example: 'Zalando Kundennummer' or 'ETA_start' |
| `data.shopify.order[].source.pattern` | `string` | no | Regex pattern with at least one capture group. Required for note, not allowed for note_attribute. The first match in the note text is used. Example: 'Return tracking codes:\s*(\S+)' |
| `data.shopify.order[].source.group` | `integer` | no | Which capture group to extract (1-indexed). Only used with note source type. Example: pattern '(carrier):\s*(\S+)' with group=2 extracts the value after 'carrier:'. |
| `data.shopify.order[].target` | `"return_tracking_number" \| "return_carrier_reference" \| "marketplace_order_number" \| "estimated_ship_date_start" \| "estimated_ship_date_end"` | yes | Valid target fields for mapping rules. |
| `data.shopify.line_item` | `array<object>` | no | Mapping rules for Shopify line item context |

#### Responses
**200** — Successfully updated mappings settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `triggers` | `object` | yes | Base Trigger Settings Schema. |
| `triggers.version` | `integer` | no | Version of the schema |
| `triggers.data` | `object` | yes | Schema for a Shop.TriggerSetting object. |
| `triggers.data.klaviyo` | `object` | yes | Schema for a Shop.KlaviyoSetting object. Inherits all fields from BaseIntegrationSettingsV1 without overrides. Klaviyo settings use the same defaults as other integrations. |
| `triggers.data.klaviyo.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.klaviyo.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.klaviyo.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.klaviyo.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.klaviyo.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.klaviyo.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `triggers.data.shopify` | `object` | yes | Schema for a Shop.ShopifySetting object. Shopify only has status and stale_event_threshold - no triggers or segments. |
| `triggers.data.shopify.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.shopify.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.emarsys` | `object` | no | Schema for a Shop.EmarsysSetting object. |
| `triggers.data.emarsys.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.emarsys.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.emarsys.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.emarsys.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.emarsys.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.emarsys.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `triggers.data.brevo` | `object` | no | Schema for a Shop.BrevoSetting object. |
| `triggers.data.brevo.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.brevo.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.brevo.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.brevo.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.brevo.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.brevo.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `triggers.data.brevo.use_proxy` | `boolean` | no | Whether to use HTTP proxy for Brevo API calls |
| `triggers.data.inxmail` | `object` | no | Schema for a Shop.InxmailSetting object. |
| `triggers.data.inxmail.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.inxmail.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.inxmail.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.inxmail.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.inxmail.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.inxmail.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `triggers.data.inxmail.instance_id` | `string` | no | Inxmail instance identifier (e.g., 'joe-nimble') |
| `triggers.data.braze` | `object` | no | Schema for a Shop.BrazeSetting object. |
| `triggers.data.braze.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.braze.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.braze.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.braze.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.braze.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.braze.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `triggers.data.braze.rest_endpoint` | `string` | no | Braze REST endpoint URL (e.g., 'https://rest.iad-03.braze.com') |
| `triggers.data.hubspot` | `object` | no | Schema for a Shop.HubSpotSetting object. Portal ID is automatically fetched from HubSpot API. No manual configuration needed. |
| `triggers.data.hubspot.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.hubspot.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.hubspot.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.hubspot.stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `triggers.data.hubspot.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.hubspot.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `triggers.data.webhook` | `object` | no | Schema for webhook settings. Inherits status, trigger_delivered_all_events, shipment_group_key, stale_event_threshold, internal_triggers, and segments_enabled from base. Webhooks are always enabled if configured. |
| `triggers.data.webhook.status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `triggers.data.webhook.trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `triggers.data.webhook.shipment_group_key` | `"shipment_id" \| "tracking_number" \| "external_shipment_id"` | no | Enum for the shipment group key. |
| `triggers.data.webhook.stale_event_threshold` | `integer` | no | Stale event threshold in hours (default: 24 for webhooks, unlike other integrations which default to 4) |
| `triggers.data.webhook.internal_triggers` | `array<object>` | no | Internal triggers |
| `triggers.data.webhook.segments_enabled` | `boolean` | no | Whether to fetch segments |
| `carriers` | `object` | yes | Base Carrier Settings Schema. |
| `carriers.version` | `integer` | no | Version of the schema |
| `carriers.data` | `object` | yes | Schema for a Shop.CarrierSettings object. |
| `carriers.data.pp_status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `carriers.data.pp_enabled_carriers` | `array<string>` | no | List of carrier references to enable for pp |
| `carriers.data.pp_disabled_carriers` | `array<string>` | no | List of carrier references to disable for pp |
| `carriers.data.override_pp_tracking_config_for_segments` | `array<string>` | no | List of segments to submit to pp regardless of tracking config |
| `carriers.data.aftership_status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `carriers.data.aftership_enabled_carriers` | `array<string>` | no | List of carrier references to enable for aftership. |
| `carriers.data.aftership_disabled_carriers` | `array<string>` | no | List of carrier references to disable for aftership. |
| `carriers.data.override_aftership_tracking_config_for_segments` | `array<string>` | no | List of segments to submit to aftership regardless of tracking config |
| `carriers.data.hc_status` | `"disabled" \| "live" \| "testing"` | no | Status enum. |
| `carriers.data.hc_enabled_carriers` | `array<string>` | no | List of carrier references to enable for hc |
| `carriers.data.hc_disabled_carriers` | `array<string>` | no | List of carrier references to disable for hc |
| `carriers.data.override_hc_tracking_config_for_segments` | `array<string>` | no | List of segments to submit to hc regardless of tracking config |
| `trackpages` | `object` | yes | Base Trackpages Settings Schema. |
| `trackpages.version` | `1 \| 2` | no | Version of the schema |
| `trackpages.data` | `object` | no | Trackpages Settings Data |
| `campaigns` | `object` | yes | Base Campaign Settings Schema. |
| `campaigns.version` | `integer` | no | Version of the schema |
| `campaigns.data` | `object` | yes | Campaign Settings Schema. |
| `campaigns.data.product_recommendations_enabled` | `boolean` | no | Flag to enable/disable dynamic campaigns |
| `brand_palette` | `object` | yes | Base Brand Palette Settings Schema. |
| `brand_palette.colors` | `object` | yes | Brand palette colors. |
| `brand_palette.colors.primary_dark` | `string` | yes | Primary dark color |
| `brand_palette.colors.primary_light` | `string` | yes | Primary light color |
| `brand_palette.colors.secondary_dark` | `string` | yes | Secondary dark color |
| `brand_palette.colors.secondary_light` | `string` | yes | Secondary light color |
| `brand_palette.colors.background` | `string` | yes | Background color |
| `brand_palette.colors.surface` | `string` | yes | Surface color |
| `mappings` | `object` | no | Base Mappings Settings Schema. |
| `mappings.version` | `integer` | no | Version of the mappings schema |
| `mappings.data` | `object` | no | Mapping rules grouped by context scope. |
| `mappings.data.shopify.order` | `array<object>` | no | Mapping rules for Shopify order context |
| `mappings.data.shopify.order[].source` | `object` | yes | Source field definition for a mapping rule. Three source types are supported: **note_attribute** — extracts a value from Shopify order note_attributes by matching on the attribute name (key). Example: ``{"type": "note_attribute", "key": "Zalando Kundennummer"}`` extracts the value of the note attribute named "Zalando Kundennummer". **note** — extracts a value from the Shopify order note (free-text) using a regex pattern with capture groups. The first match is used. Example: ``{"type": "note", "pattern": "Return tracking codes:\s*(\S+)"}`` extracts ``00341234567530088154`` from a note containing ``"Return tracking codes: 00341234567530088154"``. **line_item_property** — extracts a value from a Shopify line item property by matching on the property name (key). Example: ``{"type": "line_item_property", "key": "ETA_start"}`` extracts the value of the line item property named "ETA_start". For the **note** source type, most standard regex features are supported, including: ``\d``, ``\s``, ``\S``, ``\w``, ``\b``, ``[a-z]``, ``a+``, ``a*``, ``a?``, ``a{2,5}``, ``(?:...)``, ``(?P<name>...)``, ``(?i)`` (case-insensitive flag). |
| `mappings.data.shopify.order[].target` | `"return_tracking_number" \| "return_carrier_reference" \| "marketplace_order_number" \| "estimated_ship_date_start" \| "estimated_ship_date_end"` | yes | Valid target fields for mapping rules. |
| `mappings.data.shopify.line_item` | `array<object>` | no | Mapping rules for Shopify line item context |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/segments

**Update Shop Segment Settings**

Operation ID: `v1.shops.settings.segments.update`

Update segment settings for a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `klaviyo` | `boolean` | no | Toggle Klaviyo segment retrieval |
| `emarsys` | `boolean` | no | Toggle Emarsys segment retrieval |
| `brevo` | `boolean` | no | Toggle Brevo segment retrieval |
| `inxmail` | `boolean` | no | Toggle Inxmail segment retrieval |
| `braze` | `boolean` | no | Toggle Braze segment retrieval |
| `hubspot` | `boolean` | no | Toggle HubSpot segment retrieval |

#### Responses
**200** — Successfully updated segment settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `klaviyo` | `boolean` | yes | Klaviyo segment retrieval status |
| `shopify` | `boolean` | no | Shopify segment retrieval status |
| `emarsys` | `boolean` | yes | Emarsys segment retrieval status |
| `brevo` | `boolean` | yes | Brevo segment retrieval status |
| `inxmail` | `boolean` | yes | Inxmail segment retrieval status |
| `braze` | `boolean` | yes | Braze segment retrieval status |
| `hubspot` | `boolean` | yes | HubSpot segment retrieval status |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/border-radius

**Get Trackpages Border Radius**

Operation ID: `v1.shops.settings.trackpages.border_radius.get`

Get the current trackpages border radius settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved border radius settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `widget_corner_px` | `2 \| 4 \| 6 \| 8 \| 12 \| 16 \| 24 \| 32` | no | Border radius for widgets in pixels |
| `button_corner_px` | `2 \| 4 \| 6 \| 8 \| 12 \| 16 \| 24 \| 32` | no | Border radius for buttons in pixels |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/trackpages/border-radius

**Update Trackpages Border Radius**

Operation ID: `v1.shops.settings.trackpages.border_radius.update`

Update trackpages border radius settings for a shop.

- widget_corner_px: Border radius for widgets in pixels
- button_corner_px: Border radius for buttons in pixels (Tailwind conversion)

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `widget_corner_px` | `2 \| 4 \| 6 \| 8 \| 12 \| 16 \| 24 \| 32` | no | Border radius for widgets in pixels |
| `button_corner_px` | `2 \| 4 \| 6 \| 8 \| 12 \| 16 \| 24 \| 32` | no | Border radius for buttons in pixels |

#### Responses
**200** — Successfully updated border radius settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `widget_corner_px` | `2 \| 4 \| 6 \| 8 \| 12 \| 16 \| 24 \| 32` | no | Border radius for widgets in pixels |
| `button_corner_px` | `2 \| 4 \| 6 \| 8 \| 12 \| 16 \| 24 \| 32` | no | Border radius for buttons in pixels |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/font

**Get Trackpages Font**

Operation ID: `v1.shops.settings.trackpages.font.get`

Get the current trackpages font for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved font setting

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `font` | `string` | yes | Font family name (system font fallback if unavailable) |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/font

**Set Trackpages Font**

Operation ID: `v1.shops.settings.trackpages.font.set`

Set the trackpages font for a shop.

The font is a string with no validation - the system will fallback
to the system font if the specified font is not available.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `font` | `string` | yes | Font family name (system font fallback if unavailable) |

#### Responses
**200** — Successfully set font

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `font` | `string` | yes | Font family name (system font fallback if unavailable) |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/metadata

**Get Trackpages Metadata**

Operation ID: `v1.shops.settings.trackpages.metadata.get`

Get the current trackpages page metadata for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved page metadata

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | no | Page title |
| `description` | `string` | no | Page meta description |
| `icons` | `string` | no | Favicon URL or path |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/trackpages/metadata

**Update Trackpages Metadata**

Operation ID: `v1.shops.settings.trackpages.metadata.update`

Update trackpages page metadata for a shop.

Allows partial updates - only provided fields will be updated.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | no | Page title |
| `description` | `string` | no | Page meta description |
| `icons` | `string` | no | Favicon URL or path |

#### Responses
**200** — Successfully updated page metadata

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | no | Page title |
| `description` | `string` | no | Page meta description |
| `icons` | `string` | no | Favicon URL or path |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/theme

**Get Trackpages Theme**

Operation ID: `v1.shops.settings.trackpages.theme.get`

Get the current trackpages theme for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved trackpages theme

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme` | `"theme_1" \| "theme_2"` | yes | The theme to apply to the tracking page |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/theme

**Set Trackpages Theme**

Operation ID: `v1.shops.settings.trackpages.theme.set`

Set the trackpages theme for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme` | `"theme_1" \| "theme_2"` | yes | The theme to apply to the tracking page |

#### Responses
**200** — Successfully set trackpages theme

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme` | `"theme_1" \| "theme_2"` | yes | The theme to apply to the tracking page |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/banner-promotion

**Get Banner Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.banner_promotion.get`

Get the banner-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved banner promotion widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `enable_arrows` | `boolean` | no | Whether to show navigation arrows |
| `enable_animation` | `boolean` | no | Whether to enable animations |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/banner-promotion

**Set Banner Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.banner_promotion.set`

Set the banner-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `enable_arrows` | `boolean` | no | Whether to show navigation arrows |
| `enable_animation` | `boolean` | no | Whether to enable animations |

#### Responses
**200** — Successfully set banner promotion widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `enable_arrows` | `boolean` | no | Whether to show navigation arrows |
| `enable_animation` | `boolean` | no | Whether to enable animations |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/banner-promotion

**Delete Banner Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.banner_promotion.delete`

Delete the banner-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/basic-promotion

**Get Basic Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.basic_promotion.get`

Get the basic-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved basic promotion widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `button_variant` | `"primary" \| "secondary" \| "outline"` | no | Button style variant |
| `hide_logo` | `boolean` | no | Whether to hide the logo |
| `hide_title` | `boolean` | no | Whether to hide the title |
| `hide_subtitle` | `boolean` | no | Whether to hide the subtitle |
| `promotion_type` | `"default" \| "new"` | no | Type of promotion display |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/basic-promotion

**Set Basic Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.basic_promotion.set`

Set the basic-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `button_variant` | `"primary" \| "secondary" \| "outline"` | no | Button style variant |
| `hide_logo` | `boolean` | no | Whether to hide the logo |
| `hide_title` | `boolean` | no | Whether to hide the title |
| `hide_subtitle` | `boolean` | no | Whether to hide the subtitle |
| `promotion_type` | `"default" \| "new"` | no | Type of promotion display |

#### Responses
**200** — Successfully set basic promotion widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `button_variant` | `"primary" \| "secondary" \| "outline"` | no | Button style variant |
| `hide_logo` | `boolean` | no | Whether to hide the logo |
| `hide_title` | `boolean` | no | Whether to hide the title |
| `hide_subtitle` | `boolean` | no | Whether to hide the subtitle |
| `promotion_type` | `"default" \| "new"` | no | Type of promotion display |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/basic-promotion

**Delete Basic Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.basic_promotion.delete`

Delete the basic-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/deals

**Get Deals Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.deals.get`

Get the deals widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved deals widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `widget_type` | `"basic" \| "discount_variation" \| "deals_banner"` | no | Type of deals widget display |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/deals

**Set Deals Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.deals.set`

Set the deals widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `widget_type` | `"basic" \| "discount_variation" \| "deals_banner"` | no | Type of deals widget display |

#### Responses
**200** — Successfully set deals widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `widget_type` | `"basic" \| "discount_variation" \| "deals_banner"` | no | Type of deals widget display |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/deals

**Delete Deals Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.deals.delete`

Delete the deals widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/notification-banner

**Get Notification Banner Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.notification_banner.get`

Get the notification-banner widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved notification banner widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `content` | `string` | no | Banner content text |
| `link` | `string` | no | Link URL for the banner |
| `cta_text` | `string` | no | Call-to-action button text |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/notification-banner

**Set Notification Banner Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.notification_banner.set`

Set the notification-banner widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `content` | `string` | no | Banner content text |
| `link` | `string` | no | Link URL for the banner |
| `cta_text` | `string` | no | Call-to-action button text |

#### Responses
**200** — Successfully set notification banner widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `content` | `string` | no | Banner content text |
| `link` | `string` | no | Link URL for the banner |
| `cta_text` | `string` | no | Call-to-action button text |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/notification-banner

**Delete Notification Banner Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.notification_banner.delete`

Delete the notification-banner widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/order-finder

**Get Order Finder Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.order_finder.get`

Get the order-finder widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved order finder widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `background_type` | `"image" \| "color"` | no | Type of background (image or color) |
| `background_image` | `string` | no | URL of background image (when background_type is 'image') |
| `background_alignment` | `string` | no | Background alignment |
| `button_variant` | `"primary" \| "secondary" \| "outline"` | no | Button style variant |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/order-finder

**Set Order Finder Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.order_finder.set`

Set the order-finder widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `background_type` | `"image" \| "color"` | no | Type of background (image or color) |
| `background_image` | `string` | no | URL of background image (when background_type is 'image') |
| `background_alignment` | `string` | no | Background alignment |
| `button_variant` | `"primary" \| "secondary" \| "outline"` | no | Button style variant |

#### Responses
**200** — Successfully set order finder widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `background_type` | `"image" \| "color"` | no | Type of background (image or color) |
| `background_image` | `string` | no | URL of background image (when background_type is 'image') |
| `background_alignment` | `string` | no | Background alignment |
| `button_variant` | `"primary" \| "secondary" \| "outline"` | no | Button style variant |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/order-finder

**Delete Order Finder Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.order_finder.delete`

Delete the order-finder widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/order-summary

**Get Order Summary Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.order_summary.get`

Get the order-summary widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved order summary widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `hide_prices` | `boolean` | no | Whether to hide prices in the order summary |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/order-summary

**Set Order Summary Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.order_summary.set`

Set the order-summary widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `hide_prices` | `boolean` | no | Whether to hide prices in the order summary |

#### Responses
**200** — Successfully set order summary widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `hide_prices` | `boolean` | no | Whether to hide prices in the order summary |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/order-summary

**Delete Order Summary Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.order_summary.delete`

Delete the order-summary widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/product-promotion

**Get Product Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.product_promotion.get`

Get the product-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved product promotion widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `auto_scroll` | `boolean` | no | Whether to enable auto-scrolling |
| `show_voucher_code` | `boolean` | no | Whether to show voucher codes |
| `type` | `"product-promotion" \| "social-media" \| "others"` | no | Type of product promotion |
| `show_card_border` | `boolean` | no | Whether to show card borders |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/product-promotion

**Set Product Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.product_promotion.set`

Set the product-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `auto_scroll` | `boolean` | no | Whether to enable auto-scrolling |
| `show_voucher_code` | `boolean` | no | Whether to show voucher codes |
| `type` | `"product-promotion" \| "social-media" \| "others"` | no | Type of product promotion |
| `show_card_border` | `boolean` | no | Whether to show card borders |

#### Responses
**200** — Successfully set product promotion widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `auto_scroll` | `boolean` | no | Whether to enable auto-scrolling |
| `show_voucher_code` | `boolean` | no | Whether to show voucher codes |
| `type` | `"product-promotion" \| "social-media" \| "others"` | no | Type of product promotion |
| `show_card_border` | `boolean` | no | Whether to show card borders |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/product-promotion

**Delete Product Promotion Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.product_promotion.delete`

Delete the product-promotion widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/reviews

**Get Reviews Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.reviews.get`

Get the reviews widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved reviews widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `variant` | `"trustpilot" \| "fairing"` | no | Review platform variant |
| `redirection_link` | `string` | no | Link to redirect users for reviews |
| `redirection_email` | `string` | no | Email for review collection |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/reviews

**Set Reviews Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.reviews.set`

Set the reviews widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `variant` | `"trustpilot" \| "fairing"` | no | Review platform variant |
| `redirection_link` | `string` | no | Link to redirect users for reviews |
| `redirection_email` | `string` | no | Email for review collection |

#### Responses
**200** — Successfully set reviews widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `variant` | `"trustpilot" \| "fairing"` | no | Review platform variant |
| `redirection_link` | `string` | no | Link to redirect users for reviews |
| `redirection_email` | `string` | no | Email for review collection |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/reviews

**Delete Reviews Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.reviews.delete`

Delete the reviews widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/survey

**Get Survey Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.survey.get`

Get the survey widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved survey widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `link` | `string` | no | Survey link URL |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/survey

**Set Survey Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.survey.set`

Set the survey widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `link` | `string` | no | Survey link URL |

#### Responses
**200** — Successfully set survey widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `link` | `string` | no | Survey link URL |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/survey

**Delete Survey Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.survey.delete`

Delete the survey widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/trackpages/widgets/tracking-events

**Get Tracking Events Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.tracking_events.get`

Get the tracking-events widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved tracking events widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `show_order_number` | `boolean` | no | Whether to show the order number |
| `show_powered_by_karla` | `boolean` | no | Whether to show 'Powered by Karla' branding |
| `disable_delay_alert` | `boolean` | no | Whether to disable delay alerts |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/trackpages/widgets/tracking-events

**Set Tracking Events Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.tracking_events.set`

Set the tracking-events widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `show_order_number` | `boolean` | no | Whether to show the order number |
| `show_powered_by_karla` | `boolean` | no | Whether to show 'Powered by Karla' branding |
| `disable_delay_alert` | `boolean` | no | Whether to disable delay alerts |

#### Responses
**200** — Successfully set tracking events widget config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `object` | no | Unified color scheme for widgets using brand palette references. |
| `colors.background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Background color reference from brand palette |
| `colors.text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Text color reference from brand palette |
| `colors.accent` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Accent color reference (highlights, icons, arrows) |
| `colors.button_background` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button background color reference |
| `colors.button_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Button text color reference |
| `colors.border` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Border color reference |
| `colors.secondary_text` | `"primary_dark" \| "primary_light" \| "secondary_dark" \| "secondary_light" \| "background" \| "surface"` | no | Secondary text color reference |
| `show_order_number` | `boolean` | no | Whether to show the order number |
| `show_powered_by_karla` | `boolean` | no | Whether to show 'Powered by Karla' branding |
| `disable_delay_alert` | `boolean` | no | Whether to disable delay alerts |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/trackpages/widgets/tracking-events

**Delete Tracking Events Widget**

Operation ID: `v1.shops.settings.trackpages.widgets.tracking_events.delete`

Delete the tracking-events widget configuration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted widget configuration

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find widget configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers

**Update Shop Trigger Settings**

Operation ID: `v1.shops.settings.triggers.update`

Update trigger settings for a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `klaviyo` | `boolean` | no | Toggle sending triggers to Klaviyo |
| `shopify` | `boolean` | no | Toggle sending triggers to Shopify |
| `emarsys` | `boolean` | no | Toggle sending triggers to Emarsys |
| `brevo` | `boolean` | no | Toggle sending triggers to Brevo |
| `inxmail` | `boolean` | no | Toggle sending triggers to Inxmail |
| `braze` | `boolean` | no | Toggle sending triggers to Braze |
| `hubspot` | `boolean` | no | Toggle sending triggers to HubSpot |

#### Responses
**200** — Successfully updated trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `klaviyo` | `boolean` | yes | Karla to Klaviyo triggers status |
| `shopify` | `boolean` | yes | Karla to Shopify triggers status |
| `emarsys` | `boolean` | yes | Karla to Emarsys triggers status |
| `brevo` | `boolean` | yes | Karla to Brevo triggers status |
| `inxmail` | `boolean` | yes | Karla to Inxmail triggers status |
| `braze` | `boolean` | yes | Karla to Braze triggers status |
| `hubspot` | `boolean` | yes | Karla to HubSpot triggers status |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/braze

**Get Braze Trigger Settings**

Operation ID: `v1.shops.settings.triggers.braze.get`

Get Braze-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved Braze trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `rest_endpoint` | `string` | no | Braze REST endpoint URL |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/braze

**Update Braze Trigger Settings**

Operation ID: `v1.shops.settings.triggers.braze.update`

Update Braze-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `rest_endpoint` | `string` | no | Braze REST endpoint URL |

#### Responses
**200** — Successfully updated Braze trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `rest_endpoint` | `string` | no | Braze REST endpoint URL |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/brevo

**Get Brevo Trigger Settings**

Operation ID: `v1.shops.settings.triggers.brevo.get`

Get Brevo-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved Brevo trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/brevo

**Update Brevo Trigger Settings**

Operation ID: `v1.shops.settings.triggers.brevo.update`

Update Brevo-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |

#### Responses
**200** — Successfully updated Brevo trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/emarsys

**Get Emarsys Trigger Settings**

Operation ID: `v1.shops.settings.triggers.emarsys.get`

Get Emarsys-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved Emarsys trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/emarsys

**Update Emarsys Trigger Settings**

Operation ID: `v1.shops.settings.triggers.emarsys.update`

Update Emarsys-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |

#### Responses
**200** — Successfully updated Emarsys trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/hubspot

**Get Hubspot Trigger Settings**

Operation ID: `v1.shops.settings.triggers.hubspot.get`

Get HubSpot-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved HubSpot trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `portal_id` | `string` | no | HubSpot Portal ID |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/hubspot

**Update Hubspot Trigger Settings**

Operation ID: `v1.shops.settings.triggers.hubspot.update`

Update HubSpot-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `portal_id` | `string` | no | HubSpot Portal ID |

#### Responses
**200** — Successfully updated HubSpot trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `portal_id` | `string` | no | HubSpot Portal ID |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/inxmail

**Get Inxmail Trigger Settings**

Operation ID: `v1.shops.settings.triggers.inxmail.get`

Get Inxmail-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved Inxmail trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `instance_id` | `string` | no | Inxmail instance identifier |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/inxmail

**Update Inxmail Trigger Settings**

Operation ID: `v1.shops.settings.triggers.inxmail.update`

Update Inxmail-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `instance_id` | `string` | no | Inxmail instance identifier |

#### Responses
**200** — Successfully updated Inxmail trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `instance_id` | `string` | no | Inxmail instance identifier |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/klaviyo

**Get Klaviyo Trigger Settings**

Operation ID: `v1.shops.settings.triggers.klaviyo.get`

Get Klaviyo-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved Klaviyo trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/klaviyo

**Update Klaviyo Trigger Settings**

Operation ID: `v1.shops.settings.triggers.klaviyo.update`

Update Klaviyo-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |

#### Responses
**200** — Successfully updated Klaviyo trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/shopify

**Get Shopify Trigger Settings**

Operation ID: `v1.shops.settings.triggers.shopify.get`

Get Shopify-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved Shopify trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `stale_event_threshold` | `integer` | yes | Stale event threshold in hours |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/shopify

**Update Shopify Trigger Settings**

Operation ID: `v1.shops.settings.triggers.shopify.update`

Update Shopify-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Integration enabled status |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |

#### Responses
**200** — Successfully updated Shopify trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `stale_event_threshold` | `integer` | yes | Stale event threshold in hours |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/webhook

**Get Webhook Trigger Settings**

Operation ID: `v1.shops.settings.triggers.webhook.get`

Get webhook-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved webhook trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours (default: 24 for webhooks, unlike other integrations which default to 4) |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/settings/triggers/webhook

**Update Webhook Trigger Settings**

Operation ID: `v1.shops.settings.triggers.webhook.update`

Update webhook-specific trigger settings for a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | no | Toggle integration |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |

#### Responses
**200** — Successfully updated webhook trigger settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `boolean` | yes | Integration enabled status |
| `trigger_delivered_all_events` | `boolean` | no | Whether to trigger all events |
| `stale_event_threshold` | `integer` | no | Stale event threshold in hours (default: 24 for webhooks, unlike other integrations which default to 4) |
| `segments_enabled` | `boolean` | no | Whether to fetch segments |
| `internal_triggers` | `array<object>` | no | Internal triggers for this integration (read-only, use dedicated endpoints for CRUD operations) |
| `internal_triggers[].id` | `string` | yes | ID of the trigger |
| `internal_triggers[].name` | `string` | yes | Name of the trigger |
| `internal_triggers[].phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `internal_triggers[].phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `internal_triggers[].event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `internal_triggers[].event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `internal_triggers[].operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `internal_triggers[].time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `internal_triggers[].time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `internal_triggers[].shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/{integration}/internal-triggers

**List Internal Triggers**

Operation ID: `v1.shops.settings.triggers.internal_triggers.list`

List all internal triggers for a specific integration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `integration` | `"braze" \| "brevo" \| "emarsys" \| "hubspot" \| "inxmail" \| "klaviyo" \| "shopify" \| "webhook"` | yes | The integration name (klaviyo, emarsys, brevo, etc.) |

#### Responses
**200** — Successfully retrieved internal triggers

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/settings/triggers/{integration}/internal-triggers

**Create Internal Trigger**

Operation ID: `v1.shops.settings.triggers.internal_triggers.create`

Create a new internal trigger for a specific integration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `integration` | `"braze" \| "brevo" \| "emarsys" \| "hubspot" \| "inxmail" \| "klaviyo" \| "shopify" \| "webhook"` | yes | The integration name (klaviyo, emarsys, brevo, etc.) |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | Name of the trigger |
| `phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

#### Responses
**200** — Successfully processed operation

**201** — Successfully created internal trigger

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | ID of the trigger |
| `name` | `string` | yes | Name of the trigger |
| `phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/settings/triggers/{integration}/internal-triggers/{trigger_id}

**Get Internal Trigger**

Operation ID: `v1.shops.settings.triggers.internal_triggers.get`

Get a specific internal trigger for a specific integration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `integration` | `"braze" \| "brevo" \| "emarsys" \| "hubspot" \| "inxmail" \| "klaviyo" \| "shopify" \| "webhook"` | yes | The integration name (klaviyo, emarsys, brevo, etc.) |
| `trigger_id` | `string` | yes | The ID of the internal trigger |

#### Responses
**200** — Successfully retrieved internal trigger

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | ID of the trigger |
| `name` | `string` | yes | Name of the trigger |
| `phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PUT /v1/shops/{slug}/settings/triggers/{integration}/internal-triggers/{trigger_id}

**Update Internal Trigger**

Operation ID: `v1.shops.settings.triggers.internal_triggers.update`

Update a specific internal trigger for a specific integration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `integration` | `"braze" \| "brevo" \| "emarsys" \| "hubspot" \| "inxmail" \| "klaviyo" \| "shopify" \| "webhook"` | yes | The integration name (klaviyo, emarsys, brevo, etc.) |
| `trigger_id` | `string` | yes | The ID of the internal trigger |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | Name of the trigger |
| `phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

#### Responses
**200** — Successfully updated internal trigger

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | ID of the trigger |
| `name` | `string` | yes | Name of the trigger |
| `phase_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to trigger on |
| `phase_not_in` | `array<"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned">` | no | List of phases to not trigger on |
| `event_key_in` | `array<string>` | no | List of event keys to trigger on |
| `event_key_not_in` | `array<string>` | no | List of event keys to not trigger on |
| `operator` | `"AND" \| "OR"` | yes | Enum for the operator. |
| `time_threshold_type` | `"latest_event_time" \| "created_at"` | yes | Enum for the threshold type. |
| `time_threshold_value` | `integer` | yes | The time in hours to wait before triggering |
| `shipment_direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/settings/triggers/{integration}/internal-triggers/{trigger_id}

**Delete Internal Trigger**

Operation ID: `v1.shops.settings.triggers.internal_triggers.delete`

Delete a specific internal trigger for a specific integration.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `integration` | `"braze" \| "brevo" \| "emarsys" \| "hubspot" \| "inxmail" \| "klaviyo" \| "shopify" \| "webhook"` | yes | The integration name (klaviyo, emarsys, brevo, etc.) |
| `trigger_id` | `string` | yes | The ID of the internal trigger |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted internal trigger

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/shipments

**Search Shipments**

Operation ID: `v1.shipments.search`

Search and filter shipments for a specific shop.

    This endpoint supports filtering by tracking number, date ranges,
    and sorting. Results are paginated with a default 30-day lookback window.

    **Important**: The `updated_from` filter has a maximum lookback of 90 days.
    If not specified, it defaults to 30 days ago.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `tracking_number` | `string` | no |  |
| `updated_from` | `string` | no |  |
| `updated_to` | `string` | no |  |
| `created_from` | `string` | no |  |
| `created_to` | `string` | no |  |
| `sort` | `string` | no |  |
| `include_drafts` | `boolean` | no |  |

#### Responses
**200** — Paginated list of shipments matching the search criteria

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipments` | `array<object>` | yes | List of shipments |
| `shipments[].uuid` | `string` | yes | Shipment UUID |
| `shipments[].order_id` | `string` | no | Parent Order UUID |
| `shipments[].external_shipment_id` | `string` | no | External shipment ID |
| `shipments[].tracking_number` | `string` | no | Carrier tracking number |
| `shipments[].carrier_reference` | `string` | no | Carrier reference code |
| `shipments[].tracking_url` | `string` | no | Carrier tracking URL |
| `shipments[].phase` | `"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned"` | yes | Karla internal shipment phase describing the phase the shipment is in. |
| `shipments[].flag` | `"normal" \| "delay" \| "error"` | no | Karla internal shipment flag. Raises the possibility of failure or delay when not normal. Options: normal, delay, error. |
| `shipments[].current_event_key` | `string` | no | Current event key |
| `shipments[].zip_code` | `string` | no | Destination zip code |
| `shipments[].email_id` | `string` | no | Customer email |
| `shipments[].created_at` | `string` | no | Shipment creation timestamp |
| `shipments[].updated_at` | `string` | no | Last update timestamp |
| `shipments[].events` | `array<object>` | no | Shipment tracking events. See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details. |
| `shipments[].events[].event_key` | `any` | yes | Event Key |
| `shipments[].events[].time` | `string` | no | Event Time |
| `shipments[].events[].timezone` | `any` | no | Event Timezone |
| `shipments[].events[].location` | `any` | no | Event Location |
| `shipments[].events[].additional_info` | `any` | no | Event Additional Info |
| `shipments[].events[].phase` | `any` | yes | Phase of the shipment |
| `shipments[].events[].event_name` | `any` | yes | Shipment event name.<br>See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details.<br><details><summary>Possible values</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `shipments[].events[].event_strings` | `any` | no | Event translation strings |
| `shipments[].events[].language` | `any` | yes | The locale of the language for the event |
| `pagination` | `object` | yes | Pagination metadata for API responses. |
| `pagination.page` | `integer` | yes | Current page number |
| `pagination.per_page` | `integer` | yes | Items per page |
| `pagination.total` | `integer` | yes | Total number of items |
| `pagination.total_pages` | `integer` | yes | Calculate total number of pages. |
| `pagination.has_next` | `boolean` | yes | Check if there is a next page. |
| `pagination.has_previous` | `boolean` | yes | Check if there is a previous page. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/shipments

**Create Shipment**

Operation ID: `v1.shipments.create`

Create a new shipment for an existing order.

    This endpoint supports two modes:

    **Fulfilled Shipment** (with `tracking_number`):
    Creates a shipment with tracking information that will be submitted to
    aggregators for tracking updates. Triggers an `ORDER_PROCESSED` event.

    **Draft Shipment** (without `tracking_number`):
    Creates a placeholder shipment without tracking. Use this when you know
    an order will be split into multiple shipments but don't have tracking yet.
    Triggers an `ORDER_CREATED` event. Call this endpoint multiple times to
    create multiple draft shipments.

    **Order Identification**: Use `order_id` with `order_id_type` to specify
    which order the shipment belongs to:
    - `uuid`: Karla's internal order UUID
    - `external_id`: External platform order ID (e.g., Shopify order ID)
    - `order_number`: Merchant-visible order number
    - `order_name`: Platform-specific order name (e.g., Shopify's F-2025-31066)

    **Carrier Detection**: If `carrier_reference` is not provided, the carrier
    will be automatically detected from the tracking number pattern.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | yes | Order identifier (format depends on order_id_type) |
| `order_id_type` | `"uuid" \| "external_id" \| "order_number" \| "order_name"` | yes | Enum for order reference types. |
| `tracking_number` | `string` | no | Carrier tracking number. If not provided, creates a draft shipment (ORDER_CREATED event). |
| `carrier_reference` | `string` | no | Carrier reference code (e.g., 'dhl', 'ups'). If not provided, carrier will be auto-detected from tracking number. |
| `direction` | `"merchant_customer" \| "customer_merchant" \| "customer_partner" \| "partner_customer"` | no | Shipment Direction - indicates the flow of the shipment. MERCHANT_CUSTOMER: Standard outbound delivery from merchant to customer. CUSTOMER_MERCHANT: Customer return shipment from customer to merchant. CUSTOMER_PARTNER: Customer sends to a partner (lab, service center, etc.). PARTNER_CUSTOMER: Partner sends back to customer. |
| `external_shipment_id` | `string` | no | External shipment/return ID (e.g., Shopify return ID) |
| `products` | `array<object>` | no | Products included in this shipment (optional) |
| `products[].product_id` | `string` | yes | The product ID (Shopify product_id) |
| `products[].variant_id` | `string` | no | The variant ID (Shopify variant_id) |
| `products[].quantity` | `integer` | no | Quantity of this product in the shipment |

#### Responses
**200** — Successfully processed operation

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | Shipment UUID |
| `order_id` | `string` | no | Parent Order UUID |
| `external_shipment_id` | `string` | no | External shipment ID |
| `tracking_number` | `string` | no | Carrier tracking number |
| `carrier_reference` | `string` | no | Carrier reference code |
| `tracking_url` | `string` | no | Carrier tracking URL |
| `phase` | `"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned"` | yes | Karla internal shipment phase describing the phase the shipment is in. |
| `flag` | `"normal" \| "delay" \| "error"` | no | Karla internal shipment flag. Raises the possibility of failure or delay when not normal. Options: normal, delay, error. |
| `current_event_key` | `string` | no | Current event key |
| `zip_code` | `string` | no | Destination zip code |
| `email_id` | `string` | no | Customer email |
| `created_at` | `string` | no | Shipment creation timestamp |
| `updated_at` | `string` | no | Last update timestamp |
| `events` | `array<object>` | no | Shipment tracking events. See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details. |
| `events[].event_key` | `any` | yes | Event Key |
| `events[].time` | `string` | no | Event Time |
| `events[].timezone` | `any` | no | Event Timezone |
| `events[].location` | `any` | no | Event Location |
| `events[].additional_info` | `any` | no | Event Additional Info |
| `events[].phase` | `any` | yes | Phase of the shipment |
| `events[].event_name` | `any` | yes | Shipment event name.<br>See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details.<br><details><summary>Possible values</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `events[].event_strings` | `any` | no | Event translation strings |
| `events[].language` | `any` | yes | The locale of the language for the event |

**201** — Successfully created shipment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | Shipment UUID |
| `order_id` | `string` | no | Parent Order UUID |
| `external_shipment_id` | `string` | no | External shipment ID |
| `tracking_number` | `string` | no | Carrier tracking number |
| `carrier_reference` | `string` | no | Carrier reference code |
| `tracking_url` | `string` | no | Carrier tracking URL |
| `phase` | `"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned"` | yes | Karla internal shipment phase describing the phase the shipment is in. |
| `flag` | `"normal" \| "delay" \| "error"` | no | Karla internal shipment flag. Raises the possibility of failure or delay when not normal. Options: normal, delay, error. |
| `current_event_key` | `string` | no | Current event key |
| `zip_code` | `string` | no | Destination zip code |
| `email_id` | `string` | no | Customer email |
| `created_at` | `string` | no | Shipment creation timestamp |
| `updated_at` | `string` | no | Last update timestamp |
| `events` | `array<object>` | no | Shipment tracking events. See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details. |
| `events[].event_key` | `string` | yes | Event Key |
| `events[].time` | `string` | no | Event Time |
| `events[].timezone` | `string` | no | Event Timezone |
| `events[].location` | `object` | no | Event Location |
| `events[].additional_info` | `object` | no | Schema for a `Shipment.Event` object's additional info. |
| `events[].additional_info.pickup_point` | `string` | no |  |
| `events[].additional_info.pickup_point_url` | `string` | no |  |
| `events[].additional_info.pickup_time` | `string` | no |  |
| `events[].additional_info.pickup_opening_hours` | `object` | no |  |
| `events[].additional_info.mail_message` | `string` | no |  |
| `events[].additional_info.merchant_name` | `string` | no |  |
| `events[].additional_info.preferred_delivery_date` | `string` | no |  |
| `events[].additional_info.tracking_link` | `string` | no |  |
| `events[].additional_info.carrier_name` | `string` | no |  |
| `events[].additional_info.tracking_company` | `string` | no |  |
| `events[].additional_info.date` | `string` | no |  |
| `events[].phase` | `"collect" \| "delivery_failed" \| "delivered" \| "in_delivery" \| "in_transit" \| "order_created" \| "order_cancelled" \| "order_processed" \| "return_created" \| "return_failed" \| "return_received" \| "return_transit" \| "returned"` | yes | Karla internal shipment phase describing the phase the shipment is in. |
| `events[].event_name` | `string` | yes | Shipment event name.<br>See [Shipment Events](https://docs.gokarla.io/docs/api/entities/shipment#shipment-events) for more details.<br><details><summary>Possible values</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `events[].event_strings` | `object` | no | Tracking event strings for a specific language as defined in its lang files. |
| `events[].event_strings.event_status` | `string` | yes | Event status translation |
| `events[].event_strings.list_label` | `string` | yes | Event list label translation |
| `events[].event_strings.header_headline` | `string` | yes | Event header headline translation |
| `events[].event_strings.header_title` | `string` | yes | Event header title translation |
| `events[].event_strings.header_subtitle` | `string` | yes | Event header subtitle translation |
| `events[].language` | `"cs" \| "da" \| "nl" \| "en" \| "fi" \| "fr" \| "de" \| "gr" \| "hu" \| "it" \| "lv" \| "pl" \| "pt" \| "sk" \| "es" \| "sv"` | yes | Supported languages. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The requested resource already exists!

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/shipments/events

**Create Shipment Event**

Operation ID: `v1.shipment.events.create`

Create a new event for a shipment, identified by a reference field.

    The shipment is resolved using the `id` and `id_type` fields in the
    request body. Supported reference types: `tracking_number` (default),
    `shipment_uuid`, `external_shipment_id`, `order_number`,
    `external_order_id`, `order_uuid`.

    **Order-based lookups** (`order_number`, `external_order_id`, `order_uuid`)
    require a single shipment per order. If multiple shipments exist for the
    order, the request will return a 404 error — use `shipment_uuid` or
    `tracking_number` instead.

    **Duplicate detection**: If an identical event already exists on the
    shipment (same event key and time), the request returns a 409 Conflict.

    **Notifications**: Set `notify=true` to trigger a shipment update
    notification after the event is created.

    See [Shipment Events](https://docs.gokarla.io/platform/features/events)
    for the full list of supported event names.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `notify` | `boolean` | no | Trigger notification after event creation |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `event_name` | `string` | yes | The event to be added to the shipment. See [Shipment Events](https://docs.gokarla.io/platform/features/events) for more details.<br><details><summary>Must be one of</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `event_time` | `string` | no | The event time to be added to the shipment (defaults to current time if not given) |
| `external_id` | `string` | no | The external ID of the event. |
| `id` | `string` | yes | Reference of the shipment where you want to add the event. Supports order_number and external_order_id lookups (requires single shipment per order). Returns an error if multiple shipments exist — use shipment_uuid or tracking_number instead. |
| `id_type` | `"external_order_id" \| "external_shipment_id" \| "order_number" \| "order_uuid" \| "shipment_uuid" \| "tracking_number"` | no | Enum for shipment reference types. |

#### Responses
**200** — Successfully created shipment event

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | `array<object>` | no | Shipment tracking events |
| `events[].event_key` | `string` | yes | Event Key |
| `events[].time` | `string` | no | Event Time |
| `events[].timezone` | `string` | no | Event Timezone |
| `events[].location` | `object` | no | Event Location |
| `events[].additional_info` | `object` | no | Schema for a `Shipment.Event` object's additional info. |
| `events[].additional_info.pickup_point` | `string` | no |  |
| `events[].additional_info.pickup_point_url` | `string` | no |  |
| `events[].additional_info.pickup_time` | `string` | no |  |
| `events[].additional_info.pickup_opening_hours` | `object` | no |  |
| `events[].additional_info.mail_message` | `string` | no |  |
| `events[].additional_info.merchant_name` | `string` | no |  |
| `events[].additional_info.preferred_delivery_date` | `string` | no |  |
| `events[].additional_info.tracking_link` | `string` | no |  |
| `events[].additional_info.carrier_name` | `string` | no |  |
| `events[].additional_info.tracking_company` | `string` | no |  |
| `events[].additional_info.date` | `string` | no |  |
| `expected_delivery` | `object \| object \| null` | no | Expected delivery data |
| `additional_info` | `object` | no | Schema for a additional info sub-partial for a `Shipment.Event` object. Based on frontend representation of AdditionalInfo at https://github.com/gokarla-io/happy-app/blob/develop/lib/models/additional_info.dart#L6. |
| `additional_info.pickup_point` | `string` | no |  |
| `additional_info.pickup_point_url` | `string` | no |  |
| `additional_info.pickup_time` | `string` | no |  |
| `additional_info.pickup_opening_hours` | `object` | no |  |
| `additional_info.mail_message` | `string` | no |  |
| `additional_info.merchant_name` | `string` | no |  |
| `additional_info.preferred_delivery_date` | `string` | no |  |
| `additional_info.tracking_link` | `string` | no |  |
| `additional_info.carrier_name` | `string` | no |  |
| `additional_info.tracking_company` | `string` | no |  |
| `pickup_location` | `object` | no | Pickup Location data |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The requested resource already exists!

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/shipments/{shipment_id}/events

**Create Shipment Event by UUID**

Operation ID: `v1.shipment.events.create_by_id`

Create a new event for a shipment, identified by its UUID in the path.

    This is a convenience alternative to the reference-based endpoint.
    The shipment UUID is passed directly in the URL path instead of the
    request body.

    **Duplicate detection**: If an identical event already exists on the
    shipment (same event key and time), the request returns a 409 Conflict.

    **Notifications**: Set `notify=true` to trigger a shipment update
    notification after the event is created.

    See [Shipment Events](https://docs.gokarla.io/platform/features/events)
    for the full list of supported event names.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `shipment_id` | `string` | yes | Shipment UUID |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `notify` | `boolean` | no | Trigger notification after event creation |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `event_name` | `string` | yes | The event to be added to the shipment. See [Shipment Events](https://docs.gokarla.io/platform/features/events) for more details.<br><details><summary>Must be one of</summary>- `ACCEPTED_BY_DESTINATION_OFFICE`<br>- `ACCEPTED_BY_ORIGIN_OFFICE`<br>- `ARRIVAL_AT_FINAL_DELIVERY_CENTER`<br>- `ARRIVAL_AT_TRANSPORT_HUB`<br>- `ARRIVAL_IN_DESTINATION_COUNTRY`<br>- `ARRIVED_AT_COMMUNITY_BOX`<br>- `ARRIVED_AT_PARCEL_LOCKER`<br>- `ARRIVED_AT_PARCEL_SHOP`<br>- `ARRIVED_AT_PICKUP_POINT`<br>- `ARRIVED_AT_POST_OFFICE`<br>- `ARRIVED_AT_SORTING_CENTER`<br>- `ASSIGNED_TO_TRANSPORT`<br>- `ATTEMPTED_DELIVERY_UNDELIVERABLE`<br>- `AT_SORTING_CENTER`<br>- `AT_TRANSPORT_HUB`<br>- `CARRIER_UNKNOWN`<br>- `COMPLETION_OF_CUSTOMS_PROCESSING`<br>- `COMPLETION_OF_EXPORT_PROCESSING`<br>- `CUSTOMS_PROCESSING`<br>- `DELAY_EXPECTED`<br>- `DELAY_IN_TRANSPORT`<br>- `DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT`<br>- `DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT`<br>- `DELIVERY_ATTEMPTED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_MOVED`<br>- `DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS`<br>- `DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND`<br>- `DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY`<br>- `DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN`<br>- `DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION`<br>- `DELIVERY_ATTEMPTED_LAST_ATTEMPT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT`<br>- `DELIVERY_ATTEMPTED_RECIPIENT_VERIFICATION_UNSUCCESSFUL`<br>- `DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE`<br>- `DELIVERY_FAILED_SHIPMENT_DESTROYED`<br>- `DELIVERY_LAPSED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_LOCKER`<br>- `DELIVERY_OPTION_ALTERNATE_LOCATION_REQUESTED_SHOP`<br>- `DELIVERY_OPTION_ALTERNATE_TIME_REQUESTED`<br>- `DELIVERY_OPTION_REQUESTED_BY_RECEIVER`<br>- `DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT`<br>- `DEPARTURE_FROM_TRANSPORT_HUB`<br>- `DISPATCHED_FROM_DELIVERY_CENTER`<br>- `DISPATCHED_FROM_FORWARDING_DEPOT`<br>- `DISPATCHED_FROM_SORTING_CENTER`<br>- `DISPATCHING_STARTED_AT_PROCESSING_CENTER`<br>- `ENCODING_COMPLETED_AT_PROCESSING_CENTER`<br>- `ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `ENCODING_STARTED_AT_PROCESSING_CENTER`<br>- `ERROR_IN_PARCEL_DATA_SUBMISSION`<br>- `ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `EXPORT_PROCESSING`<br>- `FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER`<br>- `HANDED_OVER_TO_DELIVERY_PARTNER`<br>- `HELD_AT_CUSTOMS`<br>- `HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT`<br>- `HELD_AT_CUSTOMS_FOR_CLARIFICATIONS`<br>- `HELD_AT_EXPORT_PROCESSING`<br>- `INBOUND_FLIGHT_ARRIVED`<br>- `INBOUND_TRUCK_ARRIVED`<br>- `IN_DELIVERY`<br>- `ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES`<br>- `MISSING_SHIPMENT_INFORMATION`<br>- `MORE_INFO_ON_CARRIER_WEBSITE`<br>- `NOTIFICATION_SENT_TO_RECIPIENT`<br>- `NO_DELIVERY_ATTEMPT_ON_ROUTE`<br>- `ORDER_CANCELLED`<br>- `ORDER_CREATED`<br>- `ORDER_DELAYED`<br>- `ORDER_IN_PROCESSING`<br>- `ORDER_PROCESSED`<br>- `OUTBOUND_FLIGHT_DEPARTED`<br>- `OUTBOUND_TRUCK_DEPARTED`<br>- `OUT_FOR_DELIVERY`<br>- `PACKAGE_REROUTING_CANCELED_ROUTE_TO_HOME`<br>- `PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION`<br>- `PARCEL_DATA_SUBMISSION_DELAYED`<br>- `PARCEL_DATA_SUBMITTED_TO_CARRIER`<br>- `PARCEL_DISPATCHED`<br>- `PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER`<br>- `PARCEL_DROPPED_OFF_AT_POST_OFFICE`<br>- `PARCEL_DROPPED_OFF_IN_PARCEL_SHOP`<br>- `PARCEL_DROPPED_OFF_OVER_THE_COUNTER`<br>- `PARCEL_DROPPED_OFF_WITH_CARRIER`<br>- `PARCEL_READY_FOR_PICKUP`<br>- `PARCEL_TRANSFERRED_TO_THIRD_PARTY`<br>- `PATCHED`<br>- `PICKUP_ATTEMPTED`<br>- `PICKUP_DELAYED`<br>- `PICKUP_FAILED`<br>- `PICKUP_SUCCESSFUL`<br>- `PROCEEDING_TO_CARRIER_FACILITY`<br>- `PROCESSED_AT_DELIVERY_CENTER`<br>- `PROCESSING_AT_TRANSPORT_HUB`<br>- `RECEIPT_AT_FORWARDING_DEPOT`<br>- `RETURNED_TO_DELIVERY_DEPOT`<br>- `RETURN_IN_PROGRESS`<br>- `RETURN_TO_ORIGIN_COUNTRY_CANCELLED`<br>- `RETURN_TO_ORIGIN_COUNTRY_COMPLETED`<br>- `RETURN_TO_ORIGIN_COUNTRY_FAILED`<br>- `RETURN_TO_SENDER_COMPLETED`<br>- `RETURN_TO_SENDER_FAILED`<br>- `RETURN_TO_SENDER_FAILED_RECIPIENT_VERIFICATION`<br>- `SCANNED_AT_PROCESSING_CENTER`<br>- `SHIPMENT_AT_FINAL_DELIVERY_CENTER`<br>- `SHIPMENT_CANCELLED`<br>- `SHIPMENT_DAMAGED`<br>- `SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST`<br>- `SHIPMENT_EN_ROUTE`<br>- `SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER`<br>- `SHIPMENT_LOST`<br>- `SHIPMENT_LOST_IN_DELIVERY`<br>- `SHIPMENT_LOST_IN_PROCESSING`<br>- `SHIPMENT_LOST_IN_SORTING_CENTER`<br>- `SHIPMENT_LOST_IN_TRANSIT`<br>- `SHIPMENT_LOST_IN_TRANSPORT`<br>- `SHIPMENT_LOST_UNKNOWN_REASON`<br>- `SHIPMENT_MISROUTED`<br>- `SHIPMENT_NEVER_ARRIVED`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_DEPOT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_BASE`<br>- `SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER`<br>- `SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION`<br>- `SHIPMENT_REJECTED_RETURNING_TO_SENDER`<br>- `SHIPMENT_RETURNED_TO_ORIGIN_COUNTRY`<br>- `SHIPMENT_RETURNED_TO_SENDER`<br>- `SHIPMENT_RETURNING_TO_SENDER`<br>- `SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER`<br>- `SHIPMENT_UPDATED_ETA`<br>- `SHIPMENT_UPDATED_PICKUP`<br>- `SORTING_COMPLETED_AT_PROCESSING_CENTER`<br>- `SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER`<br>- `SORTING_STARTED_AT_PROCESSING_CENTER`<br>- `START_OF_CUSTOMS_PROCESSING`<br>- `START_OF_EXPORT_PROCESSING`<br>- `SUCCESSFULLY_COLLECTED`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER`<br>- `SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP`<br>- `SUCCESSFULLY_COLLECTED_AT_POST_OFFICE`<br>- `SUCCESSFULLY_DELIVERED`<br>- `SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR`<br>- `SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX`<br>- `SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED`<br>- `SUCCESSFULLY_DELIVERED_TO_NEIGHBOR`<br>- `SUCCESSFULLY_DELIVERED_TO_THE_COMMUNITY_MAILBOX`<br>- `TRANSPORT_ARRIVED`<br>- `TRANSPORT_DEPARTED`<br>- `USER_SUCCESSFULLY_DELIVERED`<br></details> |
| `event_time` | `string` | no | The event time to be added to the shipment (defaults to current time if not given) |
| `external_id` | `string` | no | The external ID of the event. |

#### Responses
**200** — Successfully created shipment event

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | `array<object>` | no | Shipment tracking events |
| `events[].event_key` | `string` | yes | Event Key |
| `events[].time` | `string` | no | Event Time |
| `events[].timezone` | `string` | no | Event Timezone |
| `events[].location` | `object` | no | Event Location |
| `events[].additional_info` | `object` | no | Schema for a `Shipment.Event` object's additional info. |
| `events[].additional_info.pickup_point` | `string` | no |  |
| `events[].additional_info.pickup_point_url` | `string` | no |  |
| `events[].additional_info.pickup_time` | `string` | no |  |
| `events[].additional_info.pickup_opening_hours` | `object` | no |  |
| `events[].additional_info.mail_message` | `string` | no |  |
| `events[].additional_info.merchant_name` | `string` | no |  |
| `events[].additional_info.preferred_delivery_date` | `string` | no |  |
| `events[].additional_info.tracking_link` | `string` | no |  |
| `events[].additional_info.carrier_name` | `string` | no |  |
| `events[].additional_info.tracking_company` | `string` | no |  |
| `events[].additional_info.date` | `string` | no |  |
| `expected_delivery` | `object \| object \| null` | no | Expected delivery data |
| `additional_info` | `object` | no | Schema for a additional info sub-partial for a `Shipment.Event` object. Based on frontend representation of AdditionalInfo at https://github.com/gokarla-io/happy-app/blob/develop/lib/models/additional_info.dart#L6. |
| `additional_info.pickup_point` | `string` | no |  |
| `additional_info.pickup_point_url` | `string` | no |  |
| `additional_info.pickup_time` | `string` | no |  |
| `additional_info.pickup_opening_hours` | `object` | no |  |
| `additional_info.mail_message` | `string` | no |  |
| `additional_info.merchant_name` | `string` | no |  |
| `additional_info.preferred_delivery_date` | `string` | no |  |
| `additional_info.tracking_link` | `string` | no |  |
| `additional_info.carrier_name` | `string` | no |  |
| `additional_info.tracking_company` | `string` | no |  |
| `pickup_location` | `object` | no | Pickup Location data |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The requested resource already exists!

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/shopify/webhooks

**Search Shopify Webhooks**

Operation ID: `v1.shopify.webhooks.list`

Get a shopify webhooks based on its uuid.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |

#### Responses
**200** — Successfully retrieved shopify webhooks

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shopify shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/shopify/webhooks

**Create Shopify Webhook**

Operation ID: `v1.shopify.webhooks.create`

Create a webhook if it does not exist.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook_type` | `"order-creation" \| "order-fulfillment" \| "order-partial-fulfillment" \| "order-update" \| "order-cancelled" \| "order-deletion" \| "order-fulfillment-update" \| "product-creation" \| "product-update" \| "product-deletion"` | yes | The type of Shopify Webhooks supported (exposed by Karla via API). |

#### Responses
**200** — Successfully created a shopify webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook_type` | `"order-creation" \| "order-fulfillment" \| "order-partial-fulfillment" \| "order-update" \| "order-cancelled" \| "order-deletion" \| "order-fulfillment-update" \| "product-creation" \| "product-update" \| "product-deletion"` | yes | The type of Shopify Webhooks supported (exposed by Karla via API). |
| `created_at` | `string` | no | Time in which the resource was created |
| `updated_at` | `string` | no | Time in which the resource was last updated after creation |
| `uuid` | `string` | yes | Webhook UUID |
| `shop_slug` | `string` | yes | Shop slug for the webhook |
| `name` | `string` | yes | Name of the webhook |
| `shopify_id` | `integer` | no | Shopify Webhook ID |
| `topic` | `"orders/create" \| "orders/fulfilled" \| "orders/partially_fulfilled" \| "orders/updated" \| "fulfillments/update" \| "orders/cancelled" \| "orders/delete" \| "products/create" \| "products/update" \| "products/delete"` | yes | Type of Shopify webhook topic. See https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics |
| `hook_url` | `string` | yes | Webhook URL |
| `fields` | `array<string>` | no | Optional inclusive fields filter |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shopify shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The requested resource already exists!

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/shopify/webhooks/webhook-type/{webhook_type}

**Get Shopify Webhook By Type**

Operation ID: `v1.shopify.webhooks.webhook-type.get`

Get a shopify webhooks based on its type.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `webhook_type` | `"order-creation" \| "order-fulfillment" \| "order-partial-fulfillment" \| "order-update" \| "order-cancelled" \| "order-deletion" \| "order-fulfillment-update" \| "product-creation" \| "product-update" \| "product-deletion"` | yes | The shopify webhook topic path |

#### Responses
**200** — Successfully retrieved a shopify webhook by type

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook_type` | `"order-creation" \| "order-fulfillment" \| "order-partial-fulfillment" \| "order-update" \| "order-cancelled" \| "order-deletion" \| "order-fulfillment-update" \| "product-creation" \| "product-update" \| "product-deletion"` | yes | The type of Shopify Webhooks supported (exposed by Karla via API). |
| `created_at` | `string` | no | Time in which the resource was created |
| `updated_at` | `string` | no | Time in which the resource was last updated after creation |
| `uuid` | `string` | yes | Webhook UUID |
| `shop_slug` | `string` | yes | Shop slug for the webhook |
| `name` | `string` | yes | Name of the webhook |
| `shopify_id` | `integer` | no | Shopify Webhook ID |
| `topic` | `"orders/create" \| "orders/fulfilled" \| "orders/partially_fulfilled" \| "orders/updated" \| "fulfillments/update" \| "orders/cancelled" \| "orders/delete" \| "products/create" \| "products/update" \| "products/delete"` | yes | Type of Shopify webhook topic. See https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics |
| `hook_url` | `string` | yes | Webhook URL |
| `fields` | `array<string>` | no | Optional inclusive fields filter |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shopify webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/shopify/webhooks/webhook-type/{webhook_type}

**Delete Shopify Webhook By Type**

Operation ID: `v1.shopify.webhooks.webhook-type.delete`

Delete a webhook that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `webhook_type` | `"order-creation" \| "order-fulfillment" \| "order-partial-fulfillment" \| "order-update" \| "order-cancelled" \| "order-deletion" \| "order-fulfillment-update" \| "product-creation" \| "product-update" \| "product-deletion"` | yes | The shopify webhook topic path |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted a shopify webhook by type

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shopify webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/shopify/webhooks/{uuid}

**Get Shopify Webhook By Uuid**

Operation ID: `v1.shopify.webhooks.get`

Get a shopify webhooks based on its uuid.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The Webhook's UUID |

#### Responses
**200** — Successfully retrieved a shopify webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook_type` | `"order-creation" \| "order-fulfillment" \| "order-partial-fulfillment" \| "order-update" \| "order-cancelled" \| "order-deletion" \| "order-fulfillment-update" \| "product-creation" \| "product-update" \| "product-deletion"` | yes | The type of Shopify Webhooks supported (exposed by Karla via API). |
| `created_at` | `string` | no | Time in which the resource was created |
| `updated_at` | `string` | no | Time in which the resource was last updated after creation |
| `uuid` | `string` | yes | Webhook UUID |
| `shop_slug` | `string` | yes | Shop slug for the webhook |
| `name` | `string` | yes | Name of the webhook |
| `shopify_id` | `integer` | no | Shopify Webhook ID |
| `topic` | `"orders/create" \| "orders/fulfilled" \| "orders/partially_fulfilled" \| "orders/updated" \| "fulfillments/update" \| "orders/cancelled" \| "orders/delete" \| "products/create" \| "products/update" \| "products/delete"` | yes | Type of Shopify webhook topic. See https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics |
| `hook_url` | `string` | yes | Webhook URL |
| `fields` | `array<string>` | no | Optional inclusive fields filter |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shopify webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/shopify/webhooks/{uuid}

**Delete Shopify Webhook By Uuid**

Operation ID: `v1.shopify.webhooks.delete`

Delete a webhook that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The webhook's unique identifier |

#### Responses
**200** — Successfully processed operation

**204** — Successfully deleted a shopify webhook

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shopify webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/users

**List Shop Users**

Operation ID: `v1.users.shop.list`

List all users assigned to a specific shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no | Page number |
| `per_page` | `integer` | no | Number of items per page |

#### Responses
**200** — Successfully retrieved users for shop

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/users

**Add User To Shop**

Operation ID: `v1.users.shop.add`

Add a user to a shop with the specified role.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | yes | User email |
| `role` | `"admin" \| "editor" \| "viewer"` | yes | The token permission scopes. |
| `create_org_permission` | `boolean` | no | Whether to create organization-level permissions. When False, only shop-specific permissions are created. |

#### Responses
**200** — Successfully added user to shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | `string` | yes | User UUID |
| `email` | `string` | yes | User email |
| `name` | `string` | no | User name |
| `picture` | `string` | no | User picture |
| `is_super_admin` | `boolean` | no | Whether the user is a super admin |
| `org_permissions` | `array<object>` | no | Organizations the user has access to |
| `org_permissions[].org_slug` | `string` | yes | Organization slug |
| `org_permissions[].role` | `"admin" \| "editor" \| "viewer"` | yes | The token permission scopes. |
| `shop_permissions` | `array<object>` | no | Shops the user has access to. Either generated from the organization permissions (inherited) or granted specifically (specific). |
| `shop_permissions[].shop_slug` | `string` | yes | Shop slug |
| `shop_permissions[].role` | `"admin" \| "editor" \| "viewer"` | yes | The token permission scopes. |
| `last_login_at` | `string` | no | User last login timestamp |
| `invitation_status` | `"pending" \| "accepted"` | no | User invitation status. |
| `feature_community` | `"alpha" \| "beta" \| "live"` | yes | Enum for identifying the feature flag community. |
| `newsletter_opt_in` | `boolean` | no | Whether the user has opted in to the newsletter |
| `consultation_opt_in` | `boolean` | no | Whether the user has opted in to the consultation |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/users/{user_id}

**Remove User From Shop**

Operation ID: `v1.users.shop.remove`

Remove a user from a shop.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `user_id` | `string` | yes | The UUID of the user to remove |

#### Responses
**200** — Successfully removed user from shop

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find requested resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/webhooks

**Search Webhooks**

Operation ID: `v1.webhooks.search`

Search all webhooks or based on some values to filter.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Query parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | no |  |
| `per_page` | `integer` | no |  |
| `uuid` | `string` | no |  |
| `status` | `"active" \| "inactive"` | no |  |
| `url` | `string` | no |  |

#### Responses
**200** — Successfully retrieved webhooks

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### POST /v1/shops/{slug}/webhooks

**Create Webhook**

Operation ID: `v1.webhooks.create`

Create a webhook if it does not exist.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled_events` | `array<string>` | no | The list of events to enable for this endpoint. `['*']` (the default) indicates that all events are enabled.See [webhooks](https://docs.gokarla.io/docs/triggers/webhooks) for more details on how to subscribe to our different events. |
| `secret` | `string` | no | The secret used to generate webhook signatures. If undefined, we will generate one for you.See [webhooks](https://docs.gokarla.io/docs/triggers/webhooks) for more details on how to validate the webhook request. |
| `description` | `string` | no | An optional description for the endpoint |
| `status` | `"active" \| "inactive"` | no | Webhook Status Type. |
| `url` | `string` | yes | The URL of the webhook endpoint |

#### Responses
**200** — Successfully created a webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled_events` | `array<string>` | no | The list of events to enable for this endpoint. `['*']` (the default) indicates that all events are enabled.See [webhooks](https://docs.gokarla.io/docs/triggers/webhooks) for more details on how to subscribe to our different events. |
| `secret` | `string` | no | The secret used to generate webhook signatures. If undefined, we will generate one for you.See [webhooks](https://docs.gokarla.io/docs/triggers/webhooks) for more details on how to validate the webhook request. |
| `description` | `string` | no | An optional description for the endpoint |
| `status` | `"active" \| "inactive"` | no | Webhook Status Type. |
| `url` | `string` | yes | The URL of the webhook endpoint |
| `created_at` | `string` | yes | The date and time the webhook was created |
| `updated_at` | `string` | yes | The date and time the webhook was last updated |
| `uuid` | `string` | yes | Unique identifier for the webhook |
| `shop_slug` | `string` | yes | Shop slug that holds the endpoint |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop related to the webhook

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**409** — The requested resource already exists!

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### PATCH /v1/shops/{slug}/webhooks/{uuid}

**Update Webhook**

Operation ID: `v1.webhooks.update`

Update a webhook partially or completely.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The webhook's unique identifier |

#### Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string` | no | An optional description for the endpoint |
| `status` | `"active" \| "inactive"` | no | Webhook Status Type. |
| `url` | `string` | no | The URL of the webhook endpoint |

#### Responses
**200** — Successfully updated a webhook

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### DELETE /v1/shops/{slug}/webhooks/{uuid}

**Delete Webhook**

Operation ID: `v1.webhooks.delete`

Delete a webhook that already exists.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |
| `uuid` | `string` | yes | The webhook's unique identifier |

#### Responses
**200** — Successfully deleted a webhook

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---

### GET /v1/shops/{slug}/woocommerce/webhook-config

**Get Webhook Config**

Operation ID: `v1.woocommerce.webhook-config.get`

Get WooCommerce webhook configuration for a shop.

Returns the delivery URL and webhook secret that should be used when
configuring a WooCommerce Order Created webhook.

#### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | yes | The slug identifying the shop |

#### Responses
**200** — Successfully retrieved WooCommerce webhook configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `delivery_url` | `string` | yes | The webhook delivery URL to configure in WooCommerce |
| `webhook_secret` | `string` | yes | The secret to use for HMAC signature verification. This should be entered in the 'Secret' field when creating the webhook in WooCommerce. |

**400** — Invalid request authentication, body or parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**401** — Invalid credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**403** — Insufficient rights to the resource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**404** — Could not find shop

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**422** — Invalid input data

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

**500** — Something went wrong on Karla's end

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `errors` | `array<object> \| any` | no | Error list |
| `key` | `"a_b_test_not_found" \| "a_b_test_overlap" \| "announcement_exists" \| "announcement_not_found" \| "campaign_active_segment_exists" \| "campaign_exists" \| "campaign_not_found" \| "campaign_product_not_found" \| "campaign_type_invalid" \| "carrier_reference_invalid" \| "deal_not_found" \| "discount_exists" \| "discount_not_found" \| "image_media_unsupported" \| "invalid_payload" \| "klaviyo_key_missing_permissions" \| "klaviyo_key_not_found" \| "order_exists" \| "order_not_found" \| "org_exists" \| "org_not_found" \| "permission_denied" \| "shipment_exists" \| "shipment_not_found" \| "shop_exists" \| "shop_fixtures_not_found" \| "shop_not_found" \| "shop_settings_not_found" \| "user_exists" \| "user_not_found" \| "webhook_exists" \| "webhook_not_found" \| "zip_code_invalid" \| "bad_gateway" \| "service_not_implemented" \| "unexpected" \| string \| null` | no | Descriptive error key. While this accepts any string for backward compatibility, the API will only return values from ErrorKeyEnum. |
| `message` | `string` | no | Generic error message |
| `type` | `"api_error" \| "invalid_request_error" \| "authentication_error"` | no | Type of errors that will be returned to the user. |

---