API Reference

This document provides technical details about Frontier Quote's API endpoints.

Storefront Endpoints

These endpoints are accessed via Shopify App Proxy and require HMAC signature verification.

POST /apps/frontier-quote/quote

Submit a quote request from the storefront.

Request

Method: POST

Headers:

  • Content-Type: application/json
  • HMAC signature in query parameters (handled by Shopify App Proxy)

Body:

{
  "shop": "your-store.myshopify.com",
  "cart": {
    "token": "cart-token",
    "items": [
      {
        "id": 123456,
        "variant_id": 789012,
        "title": "Product Name",
        "quantity": 1,
        "price": 2999,
        "properties": {}
      }
    ],
    "total_price": 2999,
    "currency": "USD"
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "company": "Acme Corp"
  },
  "shipping_address": {
    "address1": "123 Main St",
    "address2": "Suite 100",
    "city": "New York",
    "province": "NY",
    "zip": "10001",
    "country": "US"
  },
  "notes": "Customer notes here"
}

Response

Success (200):

{
  "success": true,
  "message": "Quote request submitted successfully",
  "draft_order": {
    "id": "gid://shopify/DraftOrder/123456",
    "name": "#D1234",
    "invoice_url": "https://..."
  }
}

Error (400/500):

{
  "success": false,
  "error": "Error message here"
}

GET /apps/frontier-quote/settings

Get storefront settings for quote button display.

Request

Method: GET

Query Parameters:

  • shop - Shop domain
  • country - ISO country code
  • HMAC signature (handled by Shopify App Proxy)

Response

{
  "shouldShowQuote": true,
  "popupFields": {
    "phone": true,
    "company": true,
    "notes": true
  },
  "hidePrices": false
}

Admin API Endpoints

These endpoints require Shopify session authentication and are used by the embedded admin app.

GET /app/settings

Get app settings for the current shop.

Response

{
  "whitelistCountries": ["US", "CA"],
  "blacklistCountries": ["FR", "DE", "JP"],
  "popupFields": {
    "phone": true,
    "company": false,
    "notes": true
  },
  "draftOrderTags": "gq-quote",
  "hidePrices": false,
  "onboardingComplete": true
}

POST /app/settings

Update app settings.

Request Body

{
  "whitelistCountries": ["US", "CA"],
  "blacklistCountries": ["FR", "DE"],
  "popupFields": {
    "phone": true,
    "company": true,
    "notes": false
  },
  "draftOrderTags": "gq-quote,custom-tag",
  "hidePrices": true
}

Draft Order Creation

Frontier Quote creates Draft Orders using Shopify Admin GraphQL API.

GraphQL Mutation

mutation draftOrderCreate($input: DraftOrderInput!) {
  draftOrderCreate(input: $input) {
    draftOrder {
      id
      name
      invoiceUrl
    }
    userErrors {
      field
      message
    }
  }
}

Input Format

Cart lines are converted to GraphQL GID format:

{
  "lineItems": [
    {
      "variantId": "gid://shopify/ProductVariant/789012",
      "quantity": 1,
      "originalUnitPrice": "29.99"
    }
  ],
  "email": "customer@example.com",
  "shippingAddress": {
    "address1": "123 Main St",
    "city": "New York",
    "province": "NY",
    "zip": "10001",
    "country": "US"
  },
  "tags": ["gq-quote"],
  "note": "Quote request details..."
}

Security

HMAC Verification

All storefront endpoints verify HMAC signatures provided by Shopify App Proxy. The signature is calculated using the app's shared secret and request parameters.

Rate Limiting

Rate limiting is planned for future releases to prevent abuse of the quote submission endpoint.

Error Codes

  • 400 - Bad Request (invalid input, missing required fields)
  • 401 - Unauthorized (invalid HMAC or session)
  • 404 - Not Found (shop not found or app not installed)
  • 500 - Internal Server Error

Webhooks

app/uninstalled

Triggered when the app is uninstalled. Used to clean up app data and disable storefront injection.

Next Steps