# shapescale-checkout-url-generator

> Generates, validates, and corrects ShapeScale checkout URLs with proper form_id, UTM tags, and compatibility rules. Use this skill when creating payment links, pricing pages, checkout URLs, or when validating/repairing existing links before sharing with prospects.

- Author: Niemand Assistant
- Repository: kesslerio/dialpad-clawdbot-skill
- Version: 20260127133854
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/kesslerio/dialpad-clawdbot-skill
- Web: https://mule.run/skillshub/@@kesslerio/dialpad-clawdbot-skill~shapescale-checkout-url-generator:20260127133854

---

---
name: shapescale-checkout-url-generator
description: "Generates, validates, and corrects ShapeScale checkout URLs with proper form_id, UTM tags, and compatibility rules. Use this skill when creating payment links, pricing pages, checkout URLs, or when validating/repairing existing links before sharing with prospects."
---

# ShapeScale Checkout URL Generator

## When to Activate

Use this skill whenever you need to:
- Generate a fresh ShapeScale checkout link from business requirements.
- Validate an existing checkout or pricing URL before sharing it with a prospect.
- Repair malformed links (missing UTM tags, incorrect form_id, bad encoding, wrong domain).
- Explain why a link is invalid and suggest the corrected version.

The skill now bundles Python helpers so you can **generate + validate** programmatically instead of handling parameters manually.

---

## Capabilities Overview

1. **URL Generation**
   - Determines the correct destination (`customer_collection`, `personalized_pricing_page`, `bare_pricing_page`, `direct_checkout`).
   - Selects the matching `form_id`, `product_type`, and `payment_frequency` based on the financing model.
   - Auto-populates UTM tags and recommended defaults.
   - Applies correct URL encoding and preserves parameter ordering.

2. **URL Validation**
   - Confirms domain and path are valid ShapeScale endpoints.
   - Ensures required parameters exist (form_id, UTM tags, product type).
   - Enforces compatibility rules (international vs monthly, hard case vs biennial).
   - Warns about missing analytics data (`utm_medium`, etc.).

3. **Correction + Suggestions**
   - Returns a corrected URL with normalized encoding.
  - Flags missing tags and provides suggested values.
  - Highlights why a configuration fails (e.g., “Monthly plans unavailable for international shipping”).

---

## Embedded Python Utilities

All helpers are bundled inside `scripts/` and load instantly in Claude Desktop.

```python
from scripts.url_generator import CheckoutRequest, CheckoutUrlType, generate_checkout_url
from scripts.url_validator import validate_checkout_url
```

- **Generate**:
  ```python
  request = CheckoutRequest(
      url_type=CheckoutUrlType.CUSTOMER_COLLECTION,
      financing_model="monthly",
      utm_params={"utm_source": "sales_demo", "utm_campaign": "post_demo_followup"},
      prefill_data={"email": "contact@example.com", "company": "Acme Med Spa"},
      shipping_zone=1,  # 1=US, 2=Neighbors, 3=Core Global, 4=Extended, 5=Remote
      flags={"hard_case": False},  # Boolean toggles only
      extra_params={"coupon": "DEMO20"},
  )
  url = generate_checkout_url(request)
  ```

- **Validate / Correct**:
  ```python
  result = validate_checkout_url(url)
  if not result.is_valid:
      result.corrected_url  # suggested fix
      result.errors         # blocking issues
      result.suggested_params  # missing analytics data
  ```
  ```bash
  # Standalone CLI (inside scripts/ directory)
  python url_validator.py "https://business.shapescale.com/checkout/start/?form_id=..."
  ```

Use the Python helpers before replying so the customer always receives a validated link.

- **Zone Lookup by Country**:
  ```python
  from scripts.url_generator import get_zone_for_country, SHIPPING_ZONES

  zone = get_zone_for_country("AU")  # Returns 4
  zone_info = SHIPPING_ZONES[zone]
  # {'name': 'Extended Global', 'countries': ['AU', 'NZ', ...], 'rate': 499, ...}
  ```

---

## Step-by-Step Workflow (MANDATORY)

Complete every step before sharing a URL. Stop the process if any checkpoint fails.

### Step 1: Pick the Correct Destination

| Destination | When to Use | Base URL | Notes |
|-------------|-------------|----------|-------|
| `customer_collection` | Hot lead ready to buy | `https://business.shapescale.com/checkout/start/` | Requires `form_id`, prefill available, highest conversion. |
| `personalized_pricing_page` | Warm lead comparing options | `https://business.shapescale.com/pricing` | Supports full prefill, shows all plans. |
| `bare_pricing_page` | Cold traffic with no data | `https://business.shapescale.com/pricing` | Minimal params (email only). |
| `direct_checkout` | Rare legacy flow (only if explicitly requested) | `https://shapescale.com/checkout/` | Email-only prefill, limited capabilities. |

Use the Python `CheckoutUrlType` enum to avoid typos.

### Step 2: Select Financing Model (Customer Collection Only)

| Financing Model | form_id | product_type | payment_frequency | Monthly price | Notes |
|-----------------|---------|--------------|-------------------|---------------|-------|
| `monthly` | `wf-form-lease-Form-monthly` | `lease` | `monthly` | $299 | **No international shipping.** |
| `yearly` | `wf-form-lease-Form-yearly` | `lease` | `yearly` | $199 | International allowed. |
| `biennial` | `wf-form-lease-Form-biennial` | `lease` | `biennial` | $179 | **Hard case not allowed.** |
| `lifetime` | `wf-form-Buy` OR `wf-form-purchase-Form` OR `wf-form-Purchase-Form` | `lifetime` | `null` | $9,780 | Single payment. All three form IDs are aliases. |
| `renewed` (alias: `refurb`, `refurbished`) | `wf-form-Buy` | `lifetime` | `null` | — | Campaign-only. Use customer_collection only (no pricing page). Full-price lifetime service. |

The generator reads this matrix from `form_id_matrix.json`. Validation uses the same source of truth.

### Step 3: Apply Compatibility Rules

| Invalid Combination | Reason | Guidance |
|---------------------|--------|----------|
| `shipping_zone > 1` + `monthly` | Monthly leases unavailable internationally (zones 2-5). | Offer yearly, biennial, or lifetime. |
| `international=true` + `monthly` | Legacy param; same restriction as above. | Use `shipping_zone` instead; offer yearly+. |
| `hard_case=true` + `payment_frequency=biennial` | Hard case add-on not supported with biennial leases. | Remove hard case or switch plan. |

The validator blocks these automatically and points to the correct alternative.

### Step 4: Require Full UTM Coverage

**Mandatory**: `utm_source`, `utm_campaign`  
**Recommended**: `utm_medium` (defaults to `email`), plus `utm_term`/`utm_content` if relevant.

Example palette:

| Scenario | utm_source | utm_campaign | utm_medium |
|----------|-----------|--------------|------------|
| Abandoned cart | `activecampaign` | `abandoned_cart` | `email` |
| Post-demo follow-up | `sales_demo` | `post_demo_followup` | `email` |
| Newsletter | `newsletter` | `newsletter_2025q1` | `email` |
| Cold outreach | `email` | `cold_outreach` | `email` |
| Partner referral | `partner_referral` | `{partner_name}` | `referral` |

The validator flags missing values and suggests placeholders.

### Step 5: Prefill Customer Data

Supported keys: `email`, `first_name`, `last_name`, `company`, `phone`.  
Always encode names and company fields (`Acme Med Spa` → `Acme%20Med%20Spa`).  
The generator handles encoding; the validator repairs existing links that missed it.

### Step 6: Optional Enhancements

- **Coupons**: `coupon=SAVE20NOW`, `subscription_coupon_id=LOYAL15`, or both.
- **Referral Tracking**: `ref=PARTNER123` or `tolt_referral=PARTNER123`.
- **Hard Case Toggle**: `hard_case=true` (only monthly/yearly/lifetime).
- **International Shipping Zones**: Use `shipping_zone=X` instead of legacy `international=true`:

  | Zone | Name | Rate | Delivery | Countries |
  |------|------|------|----------|-----------|
  | 1 | US | $99 | 3-7 days | US |
  | 2 | Neighbors | $199 | 5-10 days | CA, MX |
  | 3 | Core Global | $399 | 5-10 days | GB, DE, FR, IT, NL, BE, AT, CH, IE, ES, PT, SE, DK, FI, PL, GR, CZ, HU, RO, BG, HR, SK, SI, EE, LV, LT, LU, MT, CY, AD, MC, JP, KR, SG |
  | 4 | Extended Global | $499 | 7-14 days | AU, NZ, AE, IL, IN, CN |
  | 5 | Remote & Other | $599 | 14-28 days | CO, BR, ZA (+ catch-all for unlisted) |

  **Payment methods by zone:**
  - Zone 1 (US): card, link, affirm, us_bank_account, cashapp, amazon_pay
  - Zones 2-5 (International): card, link only

  Monthly leases NOT available for zones 2-5. Legacy `international=true` still works (defaults to Zone 3).

Always re-run validation after adding optional parameters.

### Step 7: Shorten with YOURLS (Recommended)

Prefer branded short links: `https://bysha.pe/...`  
If YOURLS MCP integration is unavailable, note that manual shortening is required (skill provides copy-paste instructions; generation/validation still succeeds without YOURLS).

---

## Example Workflows

### Generate + Validate a Monthly Lease Checkout Link

```python
request = CheckoutRequest(
    url_type=CheckoutUrlType.CUSTOMER_COLLECTION,
    financing_model="monthly",
    utm_params={"utm_source": "sales_demo", "utm_campaign": "post_demo_followup"},
    prefill_data={"email": "contact@acmemedispa.com", "company": "Acme Medical Spa"},
    extra_params={"coupon": "DEMO20"},
)
url = generate_checkout_url(request)
result = validate_checkout_url(url)
assert result.is_valid
```

### Validate an Existing URL Before Sending

```python
url = "https://business.shapescale.com/checkout/start/?form_id=wf-form-lease-Form-yearly&product_type=lease&payment_frequency=yearly&utm_source=sales_demo&utm_campaign=post_demo_followup"
result = validate_checkout_url(url)
if result.corrected_url:
    url = result.corrected_url  # apply encoding fixes automatically
if not result.is_valid:
    raise ValueError(result.errors)
```

### Fix a Malformed Link

Input:
```
https://business.shapescale.com/checkout/start/?form_id=wf-form-lease-Form-biennial&product_type=lease&payment_frequency=yearly&utm_source=sales demo&utm_campaign=post demo
```

Validator Output:
- Errors: `"payment_frequency 'yearly' must match biennial"`, `"Hard case add-ons..."` (if present)
- Suggested params: `utm_source`, `utm_campaign`, `payment_frequency=biennial`
- Corrected URL: encoded spaces (`%20`) applied automatically.

---

## Demo vs Checkout Links (Do Not Confuse)

- **Demo Booking** (scheduling only):
  - Standard: `https://bysha.pe/book-demo`
  - Priority: `https://bysha.pe/book-fast-demo`
- **Checkout / Pricing** (purchasing):
  - Customer collection: `https://business.shapescale.com/checkout/start/?form_id=...`
  - Personalized pricing: `https://business.shapescale.com/pricing?...`

Never send checkout links for demo rescheduling. Confirm customer intent first.

---

## CTA Contact Details

- **Sales**: sales@shapescale.com · (415) 520-1316  
- **Support**: help@shapescale.com · Text +1 (415) 991-7155  
- **Executive escalations**: martin@shapescale.com · (415) 360-2954

---

## Quality Checklist Before Responding

- [ ] Generated URL uses the Python helper (no manual string concatenation).
- [ ] Validation ran and returned `is_valid=True` (or provide corrected URL + explanation).
- [ ] UTM tags present and contextually accurate.
- [ ] Financing model + form_id align with customer intent.
- [ ] Optional YOURLS shortening performed when available.

If any checkbox fails → do not share the link. Fix the inputs and rerun generation/validation.