API Reference

Core Functions

The Shopify Module provides several public functions that can be used to interact with Shopify’s checkout system.

startTask()

The main entry point for executing a checkout task. This function orchestrates the entire checkout process from product search to payment submission. Location: Preload.js:41 Signature:

async function startTask()

Description: Initiates the complete checkout flow including:

Product search and variant selection
Cart management
Account authentication (if required)
Checkpoint/queue handling
Address submission
Shipping rate selection
Payment processing

Example:

const { startTask } = require('./Preload');

await startTask();

Task Configuration: The task requires an item object with the following structure:

item.url

string

Direct product URL (e.g., https://kith.com/products/product-handle)

item.keywords

string

Space-separated keywords for product search. Use + for required terms and - for exclusions (e.g., +yeezy +350 -toddler)

item.size

string

Size/variant to purchase. Can be numeric (9, 10, 11) or text (S, M, L, XL, OneSize)

item.randomSize

boolean

default:"false"

If true, selects a random available variant

item.color

string

Product color preference

item.delay

number

default:"0"

Delay in milliseconds before submitting checkout

item.website

string

required

Domain name (e.g., www.kith.com)

item.shopifyEmail

string

Shopify account email for authenticated checkouts

item.shopifyPassword

string

Shopify account password for authenticated checkouts

item.profile

object

required

Billing and shipping profile information

profile.firstName

string

required

First name

profile.lastName

string

required

Last name

profile.email

string

required

Contact email address

profile.phoneNumber

string

required

Phone number (digits only)

profile.address

string

required

Street address

profile.apt

string

Apartment/suite number (optional)

profile.city

string

required

City

profile.state

string

required

State/province code (e.g., NY, CA)

profile.zipCode

string

required

ZIP/postal code

profile.country

string

required

Country code (e.g., US, CA)

Credit card number (no spaces)

profile.nameOnCard

string

required

Name as it appears on card

profile.expirationMonth

number

required

Expiration month (1-12)

profile.expirationYear

number

required

Expiration year (last 2 digits, e.g., 22 for 2022)

profile.cvv

string

required

Card security code

Card type (visa, mastercard, amex, discover)

item.proxyIp

string

Proxy IP address

item.proxyPort

string

Proxy port

item.proxyUser

string

Proxy username for authentication

item.proxyPass

string

Proxy password for authentication

getUA()

Returns the user agent string used for all HTTP requests. Location: Preload.js:24 Signature:

function getUA()

return

string

User agent string for Chrome 87 on macOS

Example:

const userAgent = getUA();
// Returns: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36..."

getCaptcha()

Hook function for integrating captcha solving services. This function is called when a captcha challenge is detected. Location: Preload.js:36 Signature:

function getCaptcha(domain, sitekeylocal)

domain

string

required

The domain where the captcha needs to be solved

sitekeylocal

string

required

The reCAPTCHA site key extracted from the page

return

string

The captcha token to submit with the request

Example:

function getCaptcha(domain, sitekeylocal) {
  // Integrate your captcha solving service here
  // Example: 2Captcha, Anti-Captcha, CapMonster, etc.
  return await captchaSolver.solve({
    websiteURL: domain,
    websiteKey: sitekeylocal,
    type: 'ReCaptchaV2'
  });
}

When Called:

Account login challenge (/challenge endpoint)
Checkpoint verification (/checkpoint endpoint)
First-step captcha on checkout page

logCookies()

Utility function to extract and format cookies from a request jar. Location: Preload.js:6 Signature:

function logCookies(jar)

jar

CookieJar

required

The request-promise cookie jar instance

return

Promise<string>

Comma-separated string of all cookies in the jar

Example:

const cookieJar = request.jar();
const cookies = await logCookies(cookieJar);
console.log(cookies);
// Output: "_shopify_y=abc123, cart=xyz789, ..."

setRunningStatus()

Logs status messages to the console during task execution. Location: Preload.js:32 Signature:

function setRunningStatus(str)

str

string

required

Status message to display

Example:

setRunningStatus('Searching For Product...');
setRunningStatus('Adding to Cart...');
setRunningStatus('Submitting Address...');

Common Status Messages:

"Searching For Product..."
"Found Test Product..."
"Preloading Cart..."
"Generating Checkout Link..."
"Signing Into Account..."
"Adding to Cart Real Product..."
"Going to Checkout..."
"Polling Queue X..."
"Submitting Address..."
"Getting Shipping Rates..."
"Submitting Shipping..."
"Vaulting Card Info..."
"Checking Out..."
"Polling Checkout X..."

endRun()

Terminates the task execution and logs an error message. Location: Preload.js:28 Signature:

function endRun(err = 'error')

err

string

default:"error"

Error message to display

Example:

if (response.includes('out of stock')) {
  endRun('Product Out of Stock');
}

if (response.includes('no shipping methods')) {
  endRun('There are no shipping methods available');
}

Request Configuration

Basic Setup

All requests use request-promise with specific defaults:

const request = require('request-promise').defaults({
  followAllRedirects: true,
  resolveWithFullResponse: true,
  proxy: proxyUrl // Optional
});

const cookieJar = request.jar();

Proxy Configuration

Proxies are configured in the format:

const proxyUrl = `http://${proxyUser}:${proxyPass}@${proxyIp}:${proxyPort}`;

Note: When using proxies, SSL certificate validation is disabled:

if (proxyIp && proxyPort) {
  request.defaults({ strictSSL: false });
}

All requests should include the cookie jar to maintain session state:

await request.get({
  url: 'https://example.com',
  jar: cookieJar,
  headers: { 'user-agent': getUA() }
});

Checkout Flow Endpoints

1. Product Information

Direct Product URL:

GET {productUrl}.js
Content-Type: application/json

Products List:

GET https://{domain}/products.json?limit=250&page=1&order=updated_at

2. Add to Cart

POST https://{domain}/cart/add.js
Content-Type: application/x-www-form-urlencoded

Form Data:
  id: {variantId}
  quantity: "1"

3. Generate Checkout

POST https://{domain}/cart/checkout
Content-Type: application/x-www-form-urlencoded

Form Data:
  updates[]: 1
  attributes[checkout_clicked]: true
  checkout: ""

POST https://{domain}/account/login
Content-Type: application/x-www-form-urlencoded

Form Data:
  form_type: customer_login
  utf8: ✓
  customer[email]: {email}
  customer[password]: {password}
  checkout_url: {encodedCheckoutUrl}

5. Submit Address

POST https://{domain}/wallets/checkouts/{token}.json
Authorization: Basic {base64(apiToken)}
Content-Type: application/x-www-form-urlencoded

Form Data:
  _method: patch
  authenticity_token: {token}
  previous_step: contact_information
  step: shipping_method
  checkout[email_or_phone]: {email}
  checkout[shipping_address][first_name]: {firstName}
  checkout[shipping_address][last_name]: {lastName}
  checkout[shipping_address][address1]: {address}
  checkout[shipping_address][city]: {city}
  checkout[shipping_address][country]: {country}
  checkout[shipping_address][province]: {state}
  checkout[shipping_address][zip]: {zipCode}
  checkout[shipping_address][phone]: {phoneNumber}

6. Get Shipping Rates

GET https://{domain}/api/2020-10/checkouts/{token}/shipping_rates.json
Authorization: Basic {base64(apiToken)}

7. Submit Shipping

PUT https://{domain}/api/2020-10/checkouts/{token}.json
Authorization: Basic {base64(apiToken)}
Content-Type: application/json

JSON Body:
{
  "checkout": {
    "token": "{token}",
    "shipping_line": {
      "handle": "{shippingRateId}"
    }
  }
}

8. Vault Payment

POST https://deposit.us.shopifycs.com/sessions
Content-Type: application/json

JSON Body:
{
  "credit_card": {
    "month": 12,
    "name": "John Doe",
    "number": "4242424242424242",
    "verification_value": "123",
    "year": 2025
  }
}

string

Vaulted session ID to use in checkout submission

9. Submit Payment

POST https://{domain}/checkouts/{checkoutId}
Content-Type: application/x-www-form-urlencoded

Form Data:
  _method: patch
  authenticity_token: {token}
  previous_step: payment_method
  step: ""
  s: {vaultedSessionId}
  checkout[payment_gateway]: {gatewayId}
  checkout[credit_card][vault]: false
  checkout[different_billing_address]: false
  complete: 1

10. Poll Checkout Status

GET https://{domain}/checkouts/{checkoutId}/processing

finalUrl

string

If redirect contains thank_you or orders, checkout succeeded

Queue Handling

Detecting Queue

When checkoutURL contains /throttle/queue, the module enters queue polling mode.

GraphQL Queue Poll

POST https://{domain}/queue/poll
Content-Type: application/json

JSON Body:
{
  "query": "{ poll(token: $token) { token pollAfter } }",
  "variables": { "token": "{queueToken}" }
}

Response:

{
  "data": {
    "poll": {
      "__typename": "PollContinue",
      "token": "new-token",
      "pollAfter": "2024-01-01T12:00:00Z"
    }
  }
}

Poll continues until __typename is no longer "PollContinue".

Legacy Queue Poll

GET https://{domain}/checkout/poll?js_poll=1

Check Retry-After header and status code. Continue until status is 200.

Error Handling

Common Error Checks

// No shipping methods available
if (response.includes('There are no shipping methods available')) {
  endRun('There are no shipping methods available for your cart or address');
}

// PayPal only (no credit card)
if (!response.includes('data-gateway-name="credit_card"') && 
    response.includes('data-select-gateway=')) {
  endRun('Paypal Only');
}

// Payment declined
if (response.includes('<p class="notice__text">')) {
  const errorMessage = response
    .split('<p class="notice__text">')[1]
    .split('</p>')[0];
  console.log(errorMessage);
}

Success Detection

if (finalUrl.includes('thank_you') || finalUrl.includes('orders')) {
  console.log('Success');
  return;
}

Get Started

Guides

Reference

Core Functions

startTask()

getUA()

getCaptcha()

logCookies()

setRunningStatus()

endRun()

Request Configuration

Basic Setup

Proxy Configuration

Checkout Flow Endpoints

1. Product Information

2. Add to Cart

3. Generate Checkout

5. Submit Address

6. Get Shipping Rates

7. Submit Shipping

8. Vault Payment

9. Submit Payment

10. Poll Checkout Status

Queue Handling

Detecting Queue

GraphQL Queue Poll

Legacy Queue Poll

Error Handling

Common Error Checks

Success Detection

Build docs developers (and LLMs) love

Get Started

Guides

Reference

​Core Functions

​startTask()

​getUA()

​getCaptcha()

​logCookies()

​setRunningStatus()

​endRun()

​Request Configuration

​Basic Setup

​Proxy Configuration

​Cookie Jar Usage

​Checkout Flow Endpoints

​1. Product Information

​2. Add to Cart

​3. Generate Checkout

​4. Account Login (if required)

​5. Submit Address

​6. Get Shipping Rates

​7. Submit Shipping

​8. Vault Payment

​9. Submit Payment

​10. Poll Checkout Status

​Queue Handling

​Detecting Queue

​GraphQL Queue Poll

​Legacy Queue Poll

​Error Handling

​Common Error Checks

​Success Detection

Build docs developers (and LLMs) love

Core Functions

startTask()

getUA()

getCaptcha()

logCookies()

setRunningStatus()

endRun()

Request Configuration

Basic Setup

Proxy Configuration

Cookie Jar Usage

Checkout Flow Endpoints

1. Product Information

2. Add to Cart

3. Generate Checkout

4. Account Login (if required)

5. Submit Address

6. Get Shipping Rates

7. Submit Shipping

8. Vault Payment

9. Submit Payment

10. Poll Checkout Status

Queue Handling

Detecting Queue

GraphQL Queue Poll

Legacy Queue Poll

Error Handling

Common Error Checks

Success Detection