Skip to main content

Create or Open Quotes

In this tutorial, you'll learn how to create new quotes and access existing ones in DealHub CPQ, enabling you to manage your sales proposals effectively.

Summary of Steps​

  1. Create a new quote

    • Configure basic quote information
    • Set up customer contacts
    • Define currency and location
    • Submit quote creation request

  2. Open existing quotes

    • Prepare access credentials
    • Handle quote state
    • Update opportunity data
    • Access quote content

Requirements​

Before you begin, make sure you have:

  • DealHub Setup

    • Active DealHub account
    • Quote creation permissions
    • Access to quote templates

  • CRM Integration

    • Opportunity data ready
    • Customer information available
    • Contact details prepared

  • Configuration Details

    • Geographic region codes
    • Currency requirements
    • Quote numbering scheme

Currency settings cannot be changed after quote creation. Ensure you select the correct currency based on your customer's requirements.

New to DealHub quote management? Check out our Concepts section to understand quote lifecycles and states.

Understanding Quote Management in DealHub​

Before implementing quote operations, let's understand some key concepts:

  1. Quote Lifecycle

    • Creation: Starting a new quote with customer and opportunity data
    • Access: Opening existing quotes for viewing or editing
    • States: Draft vs. Submitted quotes
    • Currency: Immutable after quote creation

  2. Quote Context

    • Quotes are always associated with opportunities
    • Each quote maintains its opportunity information
    • Draft quotes can reflect updated opportunity data
    • Submitted quotes preserve their original information

The currency set during quote creation cannot be changed later. Make sure to select the correct currency based on your customer's requirements.

Prerequisites​

Before starting this tutorial, ensure you have:

  1. Authentication Set Up

    • Completed the authentication process
    • Valid access token
    • DealHub user ID

  2. Required Data Ready

    • Customer information
    • Opportunity details
    • Geographic and currency codes
    • Any custom fields configured in DealHub

  3. Understanding of

    • Your CRM's data structure
    • DealHub's quote workflow
    • Currency requirements

Always validate your access token before making API calls. Invalid or expired tokens will result in authentication errors.

Creating a New Quote​

Step 1: Prepare Quote Information​

First, gather all necessary information for the quote. Let's break down the key components:

Quote Configuration Example
// Identifying Information
const quoteData = {
  // Essential IDs
  dealhub_user_id: "user_123",           // From authentication
  external_opportunity_id: "opp_456",     // Your CRM's opportunity ID
  external_quote_id: "quote_789",         // Optional: Your CRM's quote ID
  
  // Names and References
  external_opportunity_name: "Q2 Deal",   // Opportunity name
  external_customer_id: "cust_101",       // Your CRM's customer ID
  customer_name: "Acme Corp"              // Customer's name
};

// Location and Currency
const locationData = {
  geo_code: "US-WEST",                    // Geographic region
  currency: "USD"                         // IMPORTANT: Cannot be changed later
};

// Contact Information
const contactData = {
  customer_contacts: [{
    first_name: "John",
    last_name: "Smith",
    title: "Procurement Manager",
    email: "john.smith@acme.com",
    phone: "555-0123",
    primary_contact: true
  }]
};

At least one contact must be marked as primary_contact: true. This contact will be the primary recipient for quote-related communications.

Step 2: Implement Quote Creation​

Use the Create Quote API:

Create Quote

POST

Endpoint: /api/v1.1/quote/create

Headers:

Authorization: Bearer <ONE_TIME_ACCESS_TOKEN>
Content-Type: application/json

Request Body:

{
  "dealhub_user_id": "111.0",
  "external_opportunity_id": "opp_456",
  "external_opportunity_name": "Q2 Deal",
  "external_customer_id": "cust_101",
  "customer_name": "Acme Corp",
  "geo_code": "US-WEST",
  "currency": "USD",
  "customer_contacts": [{
    "first_name": "John",
    "last_name": "Smith",
    "title": "Procurement Manager",
    "email": "john.smith@acme.com",
    "phone": "555-0123",
    "primary_contact": true
  }]
}

Response:

{
  "url": "https://service-eu1.dealhub.io/..../",
  "errors": []
}

Opening Existing Quotes​

Understanding Quote Access​

When opening existing quotes, consider:

  1. Quote status (draft vs. submitted)
  2. Opportunity information updates
  3. User permissions

Changes to opportunity information will only affect draft quotes. Submitted quotes maintain their original data for compliance and tracking purposes.

Step 1: Prepare Quote Access Request​

Quote Access Configuration
const quoteAccess = {
  dealhub_user_id: "user_123",
  dealhub_quote_id: "quote_789",
  external_opportunity_id: "opp_456"
};

Step 2: Implement Quote Opening​

Use the Open Quote API:

Open Quote

POST

Endpoint: /api/v2/quote/open

Headers:

Authorization: Bearer <ONE_TIME_ACCESS_TOKEN>
Content-Type: application/json

Request Body:

{
  "dealhub_user_id": "111.0",
  "dealhub_quote_id": "87948759384759",
  "external_opportunity_id": "opp_456",
  "opportunity_info": {
    "external_opportunity_name": "Q2 Deal Updated",
    "customer_name": "Acme Corp International"
  }
}

Response:

{
  "url": "https://service-eu1.dealhub.io/..../",
  "errors": []
}

Testing Your Integration​

Test Quote Creation​

Simple Quote Creation Test
async function testQuoteCreation() {
  // Basic test data
  const testQuote = {
    dealhub_user_id: "test_user_123",
    external_opportunity_id: "test_opp_456",
    external_opportunity_name: "Test Quote",
    customer_name: "Test Company",
    geo_code: "US-WEST",
    currency: "USD",
    customer_contacts: [{
      first_name: "Test",
      last_name: "User",
      email: "test@example.com",
      primary_contact: true
    }]
  };

  try {
    const response = await createQuote(testQuote);
    console.log('Quote created successfully:', response.url);
    return response;
  } catch (error) {
    console.error('Quote creation failed:', error);
    throw error;
  }
}

Verify Quote Access​

After creating a quote, verify that you can access it:

Quote Access Verification
async function verifyQuoteAccess(quoteId) {
  const accessRequest = {
    dealhub_user_id: "test_user_123",
    dealhub_quote_id: quoteId,
    external_opportunity_id: "test_opp_456"
  };

  try {
    const response = await openQuote(accessRequest);
    console.log('Quote accessed successfully:', response.url);
    return response;
  } catch (error) {
    console.error('Quote access failed:', error);
    throw error;
  }
}

Always test your integration in a sandbox environment first before moving to production.

Best Practices​

  1. Quote Creation

    • Always validate currency codes before submission
    • Include at least one primary contact
    • Use meaningful external IDs for tracking
    • Store the quote URL securely for future access

  2. Quote Access

    • Cache quote URLs with appropriate expiration
    • Update opportunity information only when necessary
    • Validate user permissions before attempting access

Implement background synchronization to keep your CRM data in sync with DealHub quotes.

Additional Resources​

For more detailed information about specific topics, refer to:

  • Quote Error Handling Guide
  • Advanced Quote Configuration
  • Quote Lifecycle Management
  • CRM Integration Best Practices

Ready to manage your quotes? Continue to View Quotes and Opportunities to learn how to track and manage your created quotes.