Dev: JavaScript API

All methods are available under:

window.refactor_apps.persistent_cart

Types

This section defines the data structures used by the Persistent Cart API.

These types describe the shape of objects returned by API methods and used in request parameters. They are referenced throughout the documentation to keep method descriptions concise and consistent.

All cart-related structures are based on the Shopify cart response format.

CartItem

Represents a Shopify cart object returned by the API.

type CartItem = {
  id: number;
  variant_id: number;
  key: string;
  quantity: number;
  title: string;
  price: number;
  line_price: number;
  final_price: number;
  final_line_price: number;
  product_id: number;
  product_title: string;
  variant_title: string | null;
  vendor: string;
  sku: string | null;
  grams: number;
  requires_shipping: boolean;
  taxable: boolean;
  product_type: string;
  url: string;
  image: string;
  handle: string;
  properties: Record<string, any>;
};

Response

Represents a Shopify cart object returned by the API.

type Response = {
  status: 200 || 204 || 401 || 404,
  message?: string,
  data?: T
};

Methods

getGuestCart()

Returns the saved guest cart for the logged-in customer.

Parameters: None

Returns:

Promise<Response<{
    items: CartItem[];
    attributes: Record<string, any>;
    note: string | null;
  }>>

Possible early responses:

  • { status: 404, message: "No guest cart token found" }  — returned if a guest cart token is not stored.
  • { status: 401, message: "You must be logged in to retrieve the guest cart" } — returned if the customer is not logged in.

Example:

const cart = await window.refactor_apps.persistent_cart.getGuestCart();

if (cart?.status === 404) {
  console.log("Guest cart token not found");
} else if (cart?.status === 401) {
  console.log("User must be logged in");
} else if (cart?.data?.items) {
  console.log("Guest cart items:", cart.data.items);
}

updateGuestCart(cart, attributes = null, note = null)

Updates the saved guest cart for the logged-in customer. Temporarily switches to the guest token, updates the cart, and restores the original token.

Parameters:

  • cart: Array<{variant_id: number, quantity: number}> — array of cart items to update.
  • attributes (optional): Object | null — additional cart attributes.
  • note (optional): string | null — a note to attach to the cart.

Returns:

Promise<Response<{
    items: CartItem[];
    attributes: Record<string, any>;
    note: string | null;
  }>>

Possible early responses:

  • { status: 404, message: "No guest cart token found" } — returned if a guest cart token is not stored.
  • { status: 401, message: "You must be logged in to update the guest cart" } — returned if the customer is not logged in.

Example:

const updatedCart = await window.refactor_apps.persistent_cart.updateGuestCart(
  [
    { variant_id: 47891250184442, quantity: 2 },
    { variant_id: 47891250086138, quantity: 1 }
  ],
);

if (updatedCart?.status === 404) {
  console.log("Guest cart token not found");
} else if (updatedCart?.status === 401) {
  console.log("User must be logged in");
} else if(cart?.data?.items) {
  console.log("Guest cart updated items:", cart.data.items);
}

addToGuestCart(cart, attributes = null, note = null)

Adds items to the saved guest cart for the logged-in customer.

Temporarily switches to the guest token, adds items to the cart, and restores the original token.

Parameters:

  • cart: Array<{variant_id: number, quantity: number}> — array of cart items to update.
  • attributes (optional): Object | null — additional cart attributes.
  • note (optional): string | null — a note to attach to the cart.

Returns:

Promise<Response<{
    items: CartItem[];
    attributes: Record<string, any>;
    note: string | null;
  }>>

Possible early responses:

  • { status: 404, message: "No guest cart token found" } — returned if a guest cart token is not stored.
  • { status: 401, message: "You must be logged in to update the guest cart" } — returned if the customer is not logged in.

Example:

const updatedCart = await window.refactor_apps.persistent_cart.updateGuestCart(
  [
    { variant_id: 47891250184442, quantity: 2 },
    { variant_id: 47891250086138, quantity: 1 }
  ],
);

if (updatedCart?.status === 404) {
  console.log("Guest cart token not found");
} else if (updatedCart?.status === 401) {
  console.log("User must be logged in");
} else if(updatedCart?.data?.items) {
  console.log("Guest cart updated items:", updatedCart.data.items);
}

clearGuestCart()

Clears the saved guest cart for the logged-in customer.

Parameters: None

Returns:

Promise<Response>

Example:

const res = await window.refactor_apps.persistent_cart.clearGuestCart();

if (res?.status === 404) {
  console.log("Guest cart token not found");
} else if (res?.status === 401) {
  console.log("User must be logged in");
} else if (res?.status === 204) {
  console.log("Guest cart has been cleared");
}

deleteGuestCart()

Deletes the saved guest cart token for the logged-in customer.

This removes the guest cart entirely from local storage and invalidates the token.

Parameters: None

Returns:

Promise<Response>

Example:

const res = await window.refactor_apps.persistent_cart.deleteGuestCart();

if (res?.status === 404) {
  console.log("Guest cart token not found");
} else if (res?.status === 401) {
  console.log("User must be logged in");
} else if (res?.status === 204) {
  console.log("Guest cart has been deleted");
}

getCustomerCart(customerId)

Retrieves the saved cart for a specific customer by their customerId.

Parameters:

customerId: number - the ID of the customer whose cart should be retrieve.

Returns:

Promise<Response<{
    items: CartItem[];
    attributes: Record<string, any>;
    note: string | null;
  }>>

Possible early responses:

  • { status: 404, message: "No remote cart token found for this customer" } — returned if customerId is not provided.
  • { status: 401, message: "You must provide customerId to retrieve the customer cart" } — returned if the customer does not have a remote cart token.

Example:

const cart = await window.refactor_apps.persistent_cart.getCustomerCart(12345678);

if (cart?.status === 404) {
  console.log("Customer cart token is not found");
} else if (cart?.status === 401) {
  console.log("CustomerId is not provided");
} else if (cart?.data?.items) {
  console.log("Customer cart items:", cart.data.items);
}

updateCustomerCart(customerId, cart, attributes = null, note = null)

Updates the saved cart for a specific customer.

If the customer does not yet have a remote cart token, a new cart is created, and the token is saved for that customer.

Parameters:

  • customerId: number - the ID of the customer whose cart should be updated.
  • cart: Array<{variant_id: number, quantity: number}> — array of cart items to update.
  • attributes (optional): Object | null — additional cart attributes.
  • note (optional): string | null — a note to attach to the cart.

Returns:

Promise<Response<{
    items: CartItem[];
    attributes: Record<string, any>;
    note: string | null;
  }>>

Possible early responses:

  • { status: 401, message: "You must provide customerId to update the customer cart" }  — returned if the customerId is not provided.

Example:

const updatedCart = await window.refactor_apps.persistent_cart.updateCustomerCart(12345678,
  [
    { variant_id: 47891250184442, quantity: 2 },
    { variant_id: 47891250086138, quantity: 1 }
  ],
);

if (updatedCart?.status === 401) {
  console.log("customerId is not provided");
} else if(cart?.data?.items) {
  console.log("Customer cart updated items:", cart.data.items);
}

addToCustomerCart(customerId, cart, attributes = null, note = null)

Adds items to the saved cart for a specific customer.

If the customer does not yet have a remote cart token, a new cart is created, and the token is saved for that customer.

Parameters:

  • customerId: number - the ID of the customer whose cart should be updated.
  • cart: Array<{variant_id: number, quantity: number}> — array of cart items to add.
  • attributes (optional): Object | null — additional cart attributes.
  • note (optional): string | null — a note to attach to the cart.

Returns:

Promise<Response<{
    items: CartItem[];
    attributes: Record<string, any>;
    note: string | null;
  }>>

Possible early responses:

  • { status: 401, message: "You must provide customerId to update the customer cart" }  — returned if customerId is not provided.

Example:

const updatedCart = await window.refactor_apps.persistent_cart.addToCustomerCart(12345678,
  [
    { variant_id: 47891250184442, quantity: 2 },
    { variant_id: 47891250086138, quantity: 1 }
  ],
);

if (updatedCart?.status === 401) {
  console.log("customerId is not provided");
} else if(cart?.data?.items) {
  console.log("Update Customer cart:", cart.data.items);
}

clearCustomerCart(customerId)

Clears the saved cart for the provided customer.

Parameters:

customerId: number - the ID of the customer whose cart should be cleared.

Returns:

Promise<Response>

Example:

const res = await window.refactor_apps.persistent_cart.clearCustomerCart(12345678);

if (res?.status === 404) {
  console.log("Customer cart token not found");
} else if (res?.status === 401) {
  console.log("CustomerId was not provided");
} else if (res?.status === 204) {
  console.log("Customer cart has been cleared");
}

deleteCustomerCart(customerId)

Deletes the saved cart token for a specific customer

Parameters:

customerId: number - the ID of the customer whose cart should be cleared.

Returns:

Promise<Response>

Example:

const res = await window.refactor_apps.persistent_cart.deleteCustomerCart(12345678);

if (res?.status === 404) {
  console.log("Customer cart token not found");
} else if (res?.status === 401) {
  console.log("CustomerId was not provided");
} else if (res?.status === 204) {
  console.log("Customer cart has been deleted");
}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us