Checkout Links

Checkout Links

Link Management

Retrieve all links for your store:

const response = await fetch(
  'https://api.checkoutlinks.com/api/v1/links?store=your-store.myshopify.com',
  {
    headers: {
      'x-api-key': 'your-api-key',
    },
  },
)

const links = await response.json()

Get a link by its shortcode:

const response = await fetch(
  'https://api.checkoutlinks.com/api/v1/links/ABC123',
  {
    headers: {
      'x-api-key': 'your-api-key',
    },
  },
)

const link = await response.json()

Basic example of a link with a single line item, 30% discount and free shipping:

const link = {
  name: 'Summer Sale 2025',
  destination: 'checkout',
  line_items: [
    {
      variant_id: '49598572101947',
      product_id: '9847762092347',
      quantity: 1,
    },
  ],
  promotions: {
    order_discount: {
      type: 'percentage',
      value: 30,
    },
    free_shipping: {
      threshold: null,
    },
  },
}

const response = await fetch('https://api.checkoutlinks.com/api/v1/links', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key',
  },
  body: JSON.stringify(link),
})

const newLink = await response.json()

Partially update an existing link:

const updates = {
  name: 'Updated Summer Sale',
  promotions: {
    order_discount: {
      value: 40, // Updated discount
    },
  },
}

const response = await fetch(
  `https://api.checkoutlinks.com/api/v1/links/${shortcode}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your-api-key',
    },
    body: JSON.stringify(updates),
  },
)

Remove a link by its shortcode:

const response = await fetch(
  'https://api.checkoutlinks.com/api/v1/links/ABC123',
  {
    method: 'DELETE',
    headers: {
      'x-api-key': 'your-api-key',
    },
  },
)

Link Configuration Options

Core Properties

name (String, Required)

The descriptive title for your link used for internal tracking and identification.

Examples:

  • "Summer Mega Sale"
  • "Back to School Promo"
  • "Holiday Gift Collection"

destination (String, Required)

Defines the link's primary routing purpose.

Options:

  • landing-page: Creates a custom, branded page before checkout
  • checkout: Directly sends customers to checkout with predefined items

type (String, Optional)

Specifies the link variant.

Details:

  • Currently supports only regular
  • Default: regular
  • Future-proofs the API for potential special link types

group_variants (Boolean, Optional)

Controls how product variants are displayed.

Behavior:

  • true (default): Similar product variants are grouped together
  • false: Each variant is shown separately

Use Case: Helpful for products with multiple sizes/colors, allowing different display strategies.

lock_cart (Boolean, Optional)

Restricts cart modifications during the checkout process.

Options:

  • true: Prevents customers from changing cart contents
  • false (default): Allows normal cart editing

Default UTM Attributes

The API automatically includes the following UTM attributes by default:

{
  "attributes": {
    "utm_id": "utm_id",
    "utm_source": "utm_source",
    "utm_medium": "utm_medium",
    "utm_campaign": "utm_campaign",
    "utm_term": "utm_term",
    "utm_content": "utm_content"
  }
}

Customizing Attributes

{
  "attributes": {
    "utm_source": "facebook",
    "utm_medium": "social",
    "utm_campaign": "summer_sale_2024",
    "utm_term": "summer_shirts",
    "utm_content": "top_banner",
    "custom_tracking_id": "campaign_001"
  }
}

Brand Customization

{
  "brand": {
    "primary": "#FF0000", // Primary brand color (hex)
    "primarycontrast": "#FFFFFF", // Text color on primary background
    "secondary": "#000000", // Secondary brand color
    "secondarycontrast": "#FFFFFF", // Text color on secondary background
    "logo": "https://example.com/logo.png" // Store logo URL
  }
}

Product Configuration

{
  "line_items": [
    // Basic product
    {
      "variant_id": "product-variant-id",
      "product_id": "product-id",
      "quantity": 1
    },
    // Product with discount
    {
      "variant_id": "variant-id",
      "product_id": "product-id",
      "quantity": 2,
      "discount_percentage": 10 // 10% off this item
    },
    // Product with quantity limits
    {
      "variant_id": "variant-id",
      "product_id": "product-id",
      "quantity": 1,
      "quantity_limits": {
        "min": 2, // Customer must buy at least 2
        "max": 5 // Customer can buy up to 5
      }
    },
    // Product with custom attributes
    {
      "variant_id": "variant-id",
      "product_id": "product-id",
      "quantity": 1,
      "custom_attributes": {
        "gift_wrap": "true",
        "engraving": "Happy Birthday"
      }
    }
  ]
}

Promotional Features

{
  "promotions": {
    // Apply specific discount codes
    "discount_codes": ["SUMMER25", "EARLYBIRD"],

    // Automatic order-level discount
    "order_discount": {
      "type": "percentage", // Discount type
      "value": 20, // 20% off
      "threshold": {
        "type": "amount", // Trigger based on total spend
        "amount": 100 // Discount applies on orders over $100
      },
      "show_progress": true // Display discount progress bar
    },

    // Free shipping configuration
    "free_shipping": {
      "threshold": 50 // Free shipping on orders over $50
      // Use `null` for unconditional free shipping
    },

    // Free gift offers
    "free_gifts": [
      {
        "variant_id": "gift-variant-id",
        "product_id": "gift-product-id",
        "quantity": 1,
        "threshold": {
          "type": "amount", // Free gift with purchase amount
          "amount": 200 // Gift added on orders over $200
        }
      },
      {
        "variant_id": "another-gift-variant",
        "product_id": "another-gift-product",
        "quantity": 1,
        "threshold": {
          "type": "quantity", // Free gift based on item count
          "amount": 3 // Gift added when buying 3+ items
        }
      }
    ]
  }
}

Advanced Options

{
  // Time-based link activation
  "schedule": {
    "start": "2024-06-01T00:00:00Z", // ISO 8601 format
    "end": "2024-06-30T23:59:59Z", // Optional end time
    "timezone": "America/New_York",
    "message": "Summer Sale Active!"
  },

  // Cart quantity restrictions
  "cart_limits": {
    "min_quantity": 2, // Minimum total items
    "max_quantity": 10 // Maximum total items
  },

  // Custom CSS for link page
  "css": "<style>.custom-class { color: red; }</style>",

  // Additional JavaScript
  "scripts": ["<script>console.log('Custom tracking');</script>"]
}

Example Full Configuration

{
  "name": "Summer Mega Sale",
  "destination": "checkout",
  "type": "regular",
  "group_variants": true,
  "lock_cart": false,

  "brand": {
    "primary": "#FF5733",
    "primarycontrast": "#FFFFFF",
    "logo": "https://example.com/logo.png"
  },

  "line_items": [
    {
      "variant_id": "summer-tshirt-red-xl",
      "product_id": "summer-tshirt",
      "quantity": 1,
      "discount_percentage": 10
    }
  ],

  "promotions": {
    "discount_codes": ["SUMMER2024"],
    "order_discount": {
      "type": "percentage",
      "value": 20,
      "threshold": {
        "type": "amount",
        "amount": 100
      },
      "show_progress": true
    },
    "free_shipping": {
      "threshold": 50
    }
  },

  "schedule": {
    "start": "2024-06-01T00:00:00Z",
    "end": "2024-06-30T23:59:59Z",
    "timezone": "America/New_York"
  },

  "attributes": {
    "utm_source": "facebook",
    "utm_campaign": "summer_sale_2024",
    "custom_tracking_id": "campaign_001"
  }
}

Response Formats

Successful Response

{
  "shortcode": "ABC123",
  "name": "Summer Sale 2025",
  "url": "store.myshopify.com/a/link/ABC123"
}

Error Response

{
  "error": "Detailed error message"
}

Error Codes

  • 200: Successful request
  • 201: Link created
  • 400: Invalid input
  • 401: Unauthorized
  • 404: Link not found
  • 500: Server error

Rate Limits

  • 100 link requests per 15-minute window
  • Rate limit headers provided

Best Practices

  1. Validation

    • Validate input before sending
    • Handle partial updates carefully

  2. Performance

    • Cache frequently used links
    • Batch create/update operations

  3. Security

    • Use secure API key management
    • Implement proper error handling

Next Steps