---
name: Qwoty
description: Use when building CPQ (Configure, Price, Quote) workflows, managing product catalogs and pricing, creating and managing quotes, integrating with CRMs/ERPs, or automating quote-to-revenue processes. Agents should reach for this skill when working with quote generation, product configuration, pricing rules, customer data, approval workflows, or API integrations.
metadata:
    mintlify-proj: qwoty
    version: "1.0"
---

# Qwoty Skill Reference

## Product Summary

Qwoty is an AI-powered CPQ (Configure, Price, Quote) platform that manages the complete quote-to-revenue workflow — from product configuration and smart pricing through e-signature, buyer collaboration (Dealroom), and order generation. It's built for sales teams in manufacturing, retail, and tech who need accurate quotes, margin control, and a single place to manage every deal.

**Key files and endpoints:**
- API base URL: `https://qwoty.app/api`
- API tokens: Generated at Settings → Developer → API Tokens (format: `qwt_prod_*`)
- Data model: Settings → Data → Data model (manage custom fields here)
- CSV import/export: Settings → Data → Import/Export Data
- Integrations: Settings → Developer → Integration (CRM, ERP, webhooks)

**Primary documentation:** https://developer.qwoty.io (API reference, integrations, core concepts)

## When to Use

Reach for this skill when:
- **Building quotes:** Creating, configuring, and managing quote workflows; setting up templates that pre-configure catalogs, pricebooks, and payment terms
- **Managing products:** Creating products, variants, bundles; organizing catalogs; defining pricing models (fixed, tiered, recurring, percentage-based)
- **Pricing strategy:** Setting up pricebooks per segment/geography; configuring discounts; managing price overrides and guardrails
- **Customer data:** Importing customers and contacts; creating customer segments; syncing customer data with CRM/ERP
- **Approval workflows:** Setting up rules that trigger manager approval based on discount level, deal size, or custom conditions
- **Integrations:** Connecting to HubSpot, Pipedrive, Salesforce, NetSuite, SAP, or custom systems via API/webhooks
- **Data migration:** Bulk importing products, prices, or customers via CSV or API
- **Dealroom & signature:** Publishing quotes for buyer review, managing e-signature, generating orders from signed quotes
- **Custom fields:** Extending the data model with custom fields on quotes, products, customers, or contracts
- **API automation:** Building integrations, syncing data, or automating quote/order workflows programmatically

## Quick Reference

### API Authentication
```bash
# All requests require Bearer token in Authorization header
Authorization: Bearer qwt_prod_your_token_here

# Example request
curl https://qwoty.app/api/quote \
  -H "Authorization: Bearer qwt_prod_your_token_here"
```

### Core Objects & API Endpoints

| Object | Key Endpoints | Purpose |
|--------|---------------|---------|
| **Quotes** | GET `/quote`, GET `/quote/{id}`, GET `/quote/{id}/pdf` | Retrieve quotes and export PDFs |
| **Products** | POST/GET/PUT `/products` | Create, list, update products |
| **Catalogs** | POST/GET/PUT `/catalogs` | Manage product catalogs |
| **Prices** | GET/PUT `/prices` | Retrieve and update prices |
| **Customers** | POST/GET/PUT `/customers` | Manage customer records |
| **Contacts** | POST/GET/PUT `/contacts` | Manage customer contacts |
| **Payment Terms** | POST/GET/PUT/DELETE `/payment-terms` | Define billing terms |
| **Addresses** | POST/GET/PUT `/addresses` | Manage billing/shipping addresses |

### Rate Limits

| Operation | Limit | Window |
|-----------|-------|--------|
| Read (GET) | 200 requests | 10 seconds |
| Write (POST, PUT, PATCH, DELETE) | 50 requests | 10 seconds |

**Response headers:** `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`

### CSV Import/Export

**Supported objects:** Master products, Products, Prices

**Volume limits:**
- CSV: Up to ~10,000 rows per file
- API: Unlimited (use for large migrations or recurring syncs)

**Import order (dependencies matter):**
1. Master products (parents)
2. Products (reference masters)
3. Prices (reference products + pricebooks)

**Catalogs, Categories, Pricebooks must exist before import.**

### Quote Statuses

| Status | Meaning |
|--------|---------|
| `Draft` | Being built by sales rep |
| `Pending Approval` | Waiting for manager review |
| `Changes Requested` | Approver sent back for revision |
| `Approved` | Manager authorized for delivery |
| `Published` | Live in Dealroom, visible to buyer |
| `Pending Signature` | Buyer reviewing/signing |
| `Accepted` | Signed; order generated automatically |
| `Expired` | Passed expiration without acceptance |
| `Lost` | Deal did not close |
| `Canceled` | Withdrawn before acceptance |

### Key Configuration Objects

| Object | Purpose | Scope |
|--------|---------|-------|
| **Template** | Bundles catalog, pricebook, payment terms, contract, approval workflow | Pre-configures every quote |
| **Catalog** | Groups products available to sell | Defines what reps can sell |
| **Pricebook** | Price list for a segment, geography, or customer | One per catalog per segment |
| **Approval Workflow** | Rules triggering manager validation | Protects margin, enforces policy |
| **Contract Model** | Legal document template with dynamic variables | Populates with quote data |
| **Dealroom** | Buyer-facing space for review, comment, signature | One per quote |

## Decision Guidance

### When to Use CSV Import vs API

| Scenario | Use CSV | Use API |
|----------|---------|---------|
| One-time migration of existing catalog | ✓ | |
| Bulk update of 100+ products | ✓ | |
| Recurring sync from ERP/CRM | | ✓ |
| Large migration (100,000+ records) | | ✓ |
| Real-time automation | | ✓ |
| Admin-driven bulk updates | ✓ | |

### When to Use Fixed vs Dynamic Pricebook

| Scenario | Fixed | Dynamic |
|----------|-------|---------|
| Absolute prices per product | ✓ | |
| Prices derived from another pricebook (e.g., +10% markup) | | ✓ |
| Regional pricing variations | | ✓ |
| Customer segment pricing | | ✓ |
| Simple, static price list | ✓ | |

### When to Use Manual vs Preconfigured Discounts

| Scenario | Manual | Preconfigured |
|----------|--------|---------------|
| Sales rep applies discount on the fly | ✓ | |
| Discount triggered by product type | | ✓ |
| Discount triggered by quote amount | | ✓ |
| Discount triggered by customer segment | | ✓ |
| One-off, ad-hoc discounts | ✓ | |

## Workflow

### Setting Up a New Quote Template

1. **Verify prerequisites exist:**
   - Catalog (Settings → Catalog)
   - Pricebook linked to that catalog (Settings → Pricebook)
   - Payment terms (Settings → Payment Terms)
   - Contract model (Settings → Documents → Contract Models)
   - Approval workflow (if needed; Settings → Workflows)

2. **Create the template:**
   - Go to Settings → Templates
   - Click New Template
   - Name it (e.g., "Enterprise SaaS", "France Catalog")
   - Select the Catalog
   - Select the Pricebook
   - Select Payment Terms
   - Link the Contract Model
   - Configure approval rules (if applicable)
   - Save

3. **Test the template:**
   - Create a test quote using the template
   - Verify catalog and pricebook auto-populate
   - Verify payment terms appear
   - Verify contract variables render correctly

4. **Assign to teams:**
   - Go to Settings → Users → Manage Teams
   - Assign the template to the appropriate team(s)

### Importing Products via CSV

1. **Prepare your data:**
   - Export example file from Settings → Data → Import/Export Data
   - Format your CSV with required columns: `api_name`, `name`, `recurrence_type` (one_off or recurring)
   - Include optional columns: `reference`, `description`, `catalog_ids`, `category_ids`, external IDs
   - Ensure all referenced catalogs and categories already exist
   - Use UTF-8 encoding, comma-separated values

2. **Create custom fields first (if needed):**
   - Go to Settings → Data → Data model
   - Click the Product object
   - Click + New to add custom fields
   - Save field definitions before importing

3. **Run the import:**
   - Go to Settings → Data → Import/Export Data
   - Select Products
   - Click Import, drop your file
   - Follow the 4-step wizard: Upload → Mapping → Confirm → Result
   - Review validation errors at Confirm step
   - Download failed rows, fix them, and re-import

4. **Verify:**
   - Check Settings → Catalog to see products appear
   - Verify prices are set (if importing prices separately)
   - Test creating a quote with the new products

### Creating a Custom Field on Quotes

1. **Define the field in the data model:**
   - Go to Settings → Data → Data model
   - Click the Template object (quote custom fields live here)
   - Click + New
   - Enter Name (e.g., "Event Date"), API Name (auto-generated), Data Type (Date, Number, Text)
   - Save

2. **Configure field behavior on the template:**
   - Go to Settings → Templates
   - Open the template where the field should appear
   - Scroll to Custom Fields section
   - Toggle the field on
   - Set properties: Mandatory (required?), Editable by sales (can reps edit?), Display for customer (show in Dealroom?)
   - Save

3. **Sync to CRM (optional):**
   - Go to Settings → Developer → Integration
   - Click your CRM (HubSpot, Pipedrive, Salesforce)
   - Find the custom field mapping section
   - Select sync direction: CRM → Qwoty, Qwoty → CRM, or Bidirectional
   - Pick the matching field in your CRM
   - Save

4. **Verify:**
   - Create a test quote using the template
   - Confirm the custom field appears in the quote editor
   - If syncing, verify it appears in your CRM after quote creation

### Integrating with HubSpot

1. **Connect Qwoty to HubSpot:**
   - Go to Settings → Developer → Integration
   - Click HubSpot card, then Connect
   - Complete OAuth flow and grant permissions

2. **Enable the Qwoty card in HubSpot:**
   - In HubSpot, go to Settings → Integrations → Connected Apps
   - Select Qwoty
   - Open App Cards tab
   - Enable Qwoty card for Deals object

3. **Add card to Deal layout:**
   - Open a Deal record in HubSpot
   - Click Customize record
   - Drag Qwoty card to desired location
   - Save

4. **Configure field mapping (optional):**
   - Return to Settings → Developer → Integration in Qwoty
   - Click HubSpot
   - Map Qwoty fields to HubSpot custom objects (quotes, products, orders)
   - Set sync direction for each field
   - Save

5. **Test:**
   - Create a quote from the Qwoty card on a HubSpot Deal
   - Verify quote data syncs back to HubSpot

## Common Gotchas

- **API token format:** Tokens start with `qwt_prod_`, not `qwoty_`. Check your Settings → Developer → API Tokens.
- **Rate limit headers:** Monitor `X-RateLimit-Remaining` to avoid hitting 429 errors. Implement exponential backoff on retries.
- **CSV import order:** Always import Master products → Products → Prices. Importing in wrong order causes validation errors.
- **Custom fields must exist before import:** CSV import creates records, not fields. Define custom fields in Data model first.
- **Pricebook must be linked to catalog:** A product won't appear in a quote if it has no price in the selected pricebook. Check catalog-pricebook linkage.
- **Template pre-configures everything:** When a sales rep selects a template, catalog and pricebook auto-populate. Changing them manually overrides the template — document this behavior.
- **Approval workflows block publishing:** If a quote triggers an approval rule, it stays in "Pending Approval" until a manager approves. Reps cannot publish without approval.
- **Dealroom is quote-specific:** One quote = one Dealroom. Publishing a quote creates a new Dealroom; you cannot reuse a Dealroom for multiple quotes.
- **Orders auto-generate on signature:** When a quote reaches "Accepted" status, an Order is created automatically. Do not manually create orders for signed quotes.
- **External IDs are optional but recommended:** If syncing with CRM/ERP, populate `id_crm`, `id_erp`, `id_accounting` fields to enable bidirectional sync.
- **Webhook retries are not ordered:** Events may be retried out of order. Design webhook handlers to be idempotent and fetch latest entity state.
- **Role permissions apply to API:** API requests respect the user's role permissions. A token tied to a Sales Rep cannot create products if the role lacks that permission.

## Verification Checklist

Before submitting work:

- [ ] **API authentication:** Token is valid, stored securely (environment variable, not hardcoded), and has correct format (`qwt_prod_*`)
- [ ] **Rate limits:** Monitoring `X-RateLimit-Remaining` header; implementing backoff for 429 responses
- [ ] **Data integrity:** CSV imports completed in correct order (masters → products → prices); no validation errors remain
- [ ] **Custom fields:** Defined in Data model before use; configured on templates with correct properties (mandatory, editable, visible)
- [ ] **Template configuration:** Catalog, pricebook, payment terms, and contract model all linked; tested with a sample quote
- [ ] **CRM/ERP sync:** Field mappings configured; sync direction set; test quote created and verified in external system
- [ ] **Webhook handlers:** Idempotent (safe to process same event twice); fetching latest entity state; returning 2xx quickly
- [ ] **Quote workflow:** Approval rules tested; Dealroom publishes correctly; signature triggers order generation
- [ ] **External IDs:** Populated on products, customers, and contracts if syncing with external systems
- [ ] **Error handling:** API errors logged with status code and message; 401/403 errors trigger token/permission review

## Resources

**Comprehensive page-by-page navigation:** https://developer.qwoty.io/llms.txt

**Critical documentation pages:**
- [API Introduction & Authentication](https://developer.qwoty.io/developers/introduction) — Getting started with API tokens and first requests
- [Data Model Reference](https://developer.qwoty.io/getting-started/data-model) — Understanding Qwoty's five domains and how objects connect
- [CPQ Key Concepts](https://developer.qwoty.io/getting-started/cpq-key-concepts) — Core vocabulary (catalogs, pricebooks, templates, quotes, approval workflows)

---

> For additional documentation and navigation, see: https://developer.qwoty.io/llms.txt