Integration Guide

Step 1: Onboarding Products

The first step in integrating with Sweet Spot is to onboard your products. Products are container objects that define the available options (e.g., Size, Color) and their possible values. Each product must have basic information like name, description, product type, and an options array that defines what variants can be created for this product.

Use the Create Product endpoint to add new products to your catalog. The price field represents a base price, but actual pricing is set per product variant (see Step 1.5). The options array defines the available option types (like Size, Color) and their possible values. When creating products, you can optionally include an externalId field to associate an ID from your own system with the Sweet Spot product. This allows you to query and attach things later by referencing your external ID, making it easier to sync data between systems and maintain relationships with your existing inventory or product management systems.

Example: Create a Product

curl -X POST https://api.thesweetspot.com/v1/products \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trail Mountain Bike",
    "description": "Premium mountain bike perfect for trail riding and off-road adventures",
    "price": 1299.00,
    "productType": "leasable",
    "productSource": "tss",
    "productCategoryId": "cat_123456",
    "organizationId": "org_123456",
    "options": [
      {
        "id": "size",
        "name": "Size",
        "position": 1,
        "values": ["Small", "Medium", "Large", "XL"]
      },
      {
        "id": "color",
        "name": "Color",
        "position": 2,
        "values": ["Red", "Blue", "Black"]
      }
    ],
    "externalId": "shopify_12345"
  }'

Step 1.5: Creating Product Variants

After creating a container product, you need to create product variants for each combination of option values. Each variant represents a specific configuration (e.g., "Medium Red" or "Large Blue") and has its own price, SKU, inventory quantity, and images. Customers will select and lease specific variants, not the container product.

Use the Create Product Variant endpoint to add variants to your product. Each variant must specify the productId of the container product, a price for this specific variant, and an options array that specifies which values were selected for each option type. You'll create one variant for each combination of option values (e.g., if you have Size: [Small, Medium, Large, XL] and Color: [Red, Blue, Black], you'll create 12 variants total).

Step 1.6: Retrieving Products

After creating products and variants, you'll need to retrieve them to display in catalogs, check details, or verify product information. You can retrieve all products with optional filtering, get a specific product by its ID, or retrieve all variants for a product.

Use the Get Products endpoint to list products with filtering options like organization, product type, or external ID. Use the Get Product by ID endpoint to retrieve detailed information about a specific product. Use the Get Product Variants endpoint to retrieve all variants for a product along with computed pricing for each available lease term.

Step 1.7: Getting Product Variant Pricing

When displaying products to customers, you may want to show the lowest available monthly payment for a product variant. This helps customers quickly understand pricing options across all available lease terms.

Use the Get Product Variant Lowest Price endpoint to retrieve the cheapest total monthly payment (monthly payment + insurance) across all available lease terms for a product variant. You can use either the variant's public ID (format: pvar_xxxxx) or external ID.

Example: Get Lowest Price for a Product Variant

curl https://api.thesweetspot.com/v1/product-variants/pvar_123456/lowest \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY_HERE"

Step 2: Creating Checkouts with Customers

Once you have products in your catalog, you can create checkouts for customers. A checkout represents a customer's intent to lease a product. The checkout process collects customer information and allows them to select lease terms.

Use the Create Checkout endpoint to create a new checkout. You must provide a productVariantId(not a product ID) to specify which product variant the customer wants to lease. Since pricing is set per variant, checkouts always require a specific variant ID. If you provide an optionalcustomer object, the system will lookup an existing customer by email or create a new customer. If no customer information is provided, the checkout is created for the authenticated user. This is the recommended approach for creating checkouts with customer information in a single request.

Example: Create a Checkout with Customer

curl -X POST https://api.thesweetspot.com/v1/checkouts \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "productVariantId": "pvar_123456",
    "selectedTermInMonths": "12",
    "customer": {
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Step 3: Retrieving Checkouts

After creating checkouts, you'll need to retrieve them to check their status, display information to customers, or process updates. You can retrieve all checkouts or a specific checkout by ID.

Use the Get Checkouts endpoint to list all checkouts, or the Get Checkout by ID endpoint to retrieve a specific checkout's details.

Step 4: Making Updates to Checkouts and Products

As your business evolves, you'll need to update products, product variants, and checkouts. Products may need description or status updates, product variants may need price changes or inventory updates, while checkouts may need state changes or lease term modifications.

Use the Update Product endpoint to modify product details, the Update Product Variant endpoint to modify variant-specific details like price and inventory, or the Update Checkout endpoint to change checkout state or lease terms.

Step 5: Retrieving User Information

When building user-facing applications, you'll need to retrieve information about the authenticated user and their permissions. This is useful for displaying user profiles, checking authorization, and customizing the user experience based on their role and permissions.

Use the Get Current User endpoint to retrieve the authenticated user's profile information including user details and associated customer record. Use the Get User Permissions endpoint to retrieve the user's authorization principal including all permissions, roles, and organization memberships.