Skip to main content

API Design & Contracts

The Pricing Engine exposes a robust REST API under the /pricing namespace. All endpoints require authenticating via a valid JWT bearer token. Multi-tenancy is enforced natively in the service layer using the authenticated user's vendorId.

📌 Endpoint Summary​

HTTP MethodRouteAuth RequiredDescription
POST/api/v1/pricing/estimateYesRequest a new campaign cost estimate and quotation.
GET/api/v1/pricing/historyYesList paginated quotation history for the active tenant.
GET/api/v1/pricing/:quoteNumberYesFetch a specific quotation details (used to poll PDF status).
GET/api/v1/pricing/:quoteNumber/pdfYesDownload the generated PDF quotation artifact.

🚀 API Endpoint Specifications​

1. Request Campaign Estimate​

Generates a pricing calculation immediately. Commits the quotation to the database and dispatches an asynchronous task to the BullMQ processing queue for PDF rendering.

  • URL: /api/v1/pricing/estimate
  • Method: POST
  • Headers:
    • Authorization: Bearer <JWT>
    • Content-Type: application/json

Request Payload DTO​

{
  "templateCategory": "MARKETING",
  "audience": {
    "type": "LABEL",
    "ids": ["9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "4c9d8b7a-6e5d-4c3b-2a1f-0e9d8c7b6a5f"]
  }
}

Response Payload (Shared WABA Tenant)​

{
  "quotationId": "8b5f928c-0624-4f05-8964-32e604baefd1",
  "quoteNumber": "KQ-2026-00042",
  "status": "ISSUED",
  "summary": {
    "templateCategory": "MARKETING",
    "audienceType": "LABEL",
    "totalRecipients": 5155,
    "validRecipients": 5143,
    "excludedContacts": 0,
    "duplicateRecipients": 12,
    "invalidRecipients": 0
  },
  "breakdown": [
    {
      "countryCode": "IN",
      "countryName": "India",
      "regionGroup": "SOUTH_ASIA",
      "recipientCount": 5000,
      "ratePerUnit": "0.780000",
      "subtotal": "3900.0000"
    },
    {
      "countryCode": "US",
      "countryName": "United States",
      "regionGroup": "NORTH_AMERICA",
      "recipientCount": 143,
      "ratePerUnit": "2.050000",
      "subtotal": "293.1500"
    }
  ],
  "pricing": {
    "estimatedMetaCost": "4193.1500",
    "platformFee": "1048.2875",
    "estimatedTotal": "5241.4375",
    "currency": "INR"
  },
  "wallet": {
    "walletApplicable": true,
    "walletBalance": "8500.0000",
    "walletSufficient": true
  },
  "estimation": {
    "engineVersion": "1.0.0",
    "confidence": "HIGH",
    "disclaimer": "This quotation is an estimate based on current Meta per-message pricing. Final charges are determined by Meta at delivery time. Valid for 7 days.",
    "snapshotId": "f7d9c8b7-a6e5-4d3c-2b1a-0f9e8d7c6b5a"
  },
  "pdf": {
    "status": "GENERATING",
    "url": null
  },
  "validUntil": "2026-05-24T08:25:00.000Z"
}

2. Fetch Quotation Details (Polling API)​

Retrieves quotation status. Used by the frontend client to poll for the completed PDF document.

  • URL: /api/v1/pricing/:quoteNumber
  • Method: GET
  • Params:
    • quoteNumber: e.g., KQ-2026-00042

Response Payload (Once PDF is ready)​

{
  "quotationId": "8b5f928c-0624-4f05-8964-32e604baefd1",
  "quoteNumber": "KQ-2026-00042",
  "status": "ISSUED",
  "summary": {
    "templateCategory": "MARKETING",
    "audienceType": "LABEL",
    "totalRecipients": 5155,
    "validRecipients": 5143,
    "excludedContacts": 0,
    "duplicateRecipients": 12,
    "invalidRecipients": 0
  },
  "breakdown": [
    {
      "countryCode": "IN",
      "countryName": "India",
      "regionGroup": "SOUTH_ASIA",
      "recipientCount": 5000,
      "ratePerUnit": "0.780000",
      "subtotal": "3900.0000"
    },
    {
      "countryCode": "US",
      "countryName": "United States",
      "regionGroup": "NORTH_AMERICA",
      "recipientCount": 143,
      "ratePerUnit": "2.050000",
      "subtotal": "293.1500"
    }
  ],
  "pricing": {
    "estimatedMetaCost": "4193.1500",
    "platformFee": "1048.2875",
    "estimatedTotal": "5241.4375",
    "currency": "INR"
  },
  "wallet": {
    "walletApplicable": true,
    "walletBalance": "8500.0000",
    "walletSufficient": true
  },
  "estimation": {
    "engineVersion": "1.0.0",
    "confidence": "HIGH",
    "disclaimer": "This quotation is an estimate based on current Meta per-message pricing. Final charges are determined by Meta at delivery time. Valid for 7 days.",
    "snapshotId": "f7d9c8b7-a6e5-4d3c-2b1a-0f9e8d7c6b5a"
  },
  "pdf": {
    "status": "READY",
    "url": "/api/v1/pricing/KQ-2026-00042/pdf"
  },
  "validUntil": "2026-05-24T08:25:00.000Z"
}

3. Download PDF Quotation​

Streams the generated PDF binary file.

  • URL: /api/v1/pricing/:quoteNumber/pdf
  • Method: GET
  • Response Headers:
    • Content-Type: application/pdf
    • Content-Disposition: attachment; filename="KQ-2026-00042.pdf"
  • Response: Binary PDF Stream.