Skip to main content
POST
/
{proxy_path_prefix}
/
intents
curl --request POST \
  --url https://api.example.com/{proxy_path_prefix}/intents \
  --header 'Content-Type: application/json' \
  --data '
{
  "variant_id": 123456789,
  "option": {
    "global_id": "gid://supercycle/CalendarRental::RentalPeriod/1",
    "params": {
      "rental_start": "2025-01-01"
    }
  }
}
'
{
  "attributes": {
    "properties[_cycle]": "{...}",
    "properties[_validations]": "{...}",
    "selling_plan": 1234
  },
  "add_ons": [],
  "available_item_count": 3
}
Returns the form attributes required to turn a line item into a Cycle when added to the cart. Each rental method (subscription, membership, calendar, resale) stores its options in a product metafield. Every option has a global_id that is passed to this endpoint.
MetafieldMethod
product.metafields.supercycle.calendar_configurationCalendar
product.metafields.supercycle.subscription_configurationSubscription
product.metafields.supercycle.membership_configurationMembership
product.metafields.supercycle.resale_configurationResale
The options array within each metafield contains a global_id for each option: 
{
  "rental_periods": [
    { "global_id": "gid://supercycle/CalendarRental::RentalPeriod/1" },
    { "global_id": "gid://supercycle/CalendarRental::RentalPeriod/2" }
  ]
}
Once you have the variant ID and option global_id, call this endpoint to get the attributes that need to be attached to the line item so Supercycle processes it as a Cycle. The response attributes object contains key-value pairs that must be included when submitting the add-to-cart form. Each entry should be added as a hidden input on the product form, or included in the request body when submitting via AJAX. See Cycle line item property and Validations line item property for the full schema. Hidden inputs: 
Object.entries(intent.attributes).forEach(([name, value]) => {
  const input = document.createElement("input");
  input.type = "hidden";
  input.name = name;
  input.value = value;
  addToCartForm.appendChild(input);
});
AJAX (fetch): 
const formData = new FormData(addToCartForm);

Object.entries(intent.attributes).forEach(([name, value]) => {
  formData.set(name, value);
});

await fetch("/cart/add.js", { method: "POST", body: formData });

​
Add-ons

add_ons are additional variants that must be submitted in the same request using Shopify’s multiple items cart API format. Each add-on property (except cart_quantity) should be included as items[n][property]: 
// Example for a single add-on
// items[0][id] = 4321
// items[0][quantity] = 1
// items[0][selling_plan] = 1234
intent.add_ons.forEach(({ cart_quantity, ...addOnAttributes }, index) => {
  Object.entries(addOnAttributes).forEach(([key, value]) => {
    formData.set(`items[${index}][${key}]`, value);
  });
});
cart_quantity is not submitted — it is the maximum total quantity of that variant that should be present in the cart. Before adding the add-on, check the current cart to see if the variant is already there and skip if the quantity would exceed cart_quantity.

Path Parameters

​
proxy_path_prefix
string
required

The Shopify proxy path prefix configured for the app (e.g., 'customer_portal')

Body

application/json
​
variant_id
integer
required

Shopify ID of the variant to create an intent for

​
option
object
required

Response

Successful response with intent attributes and add-ons

​
attributes
object
required

Key-value pairs to be submitted with the Shopify add-to-cart form. Includes line item properties (keys prefixed with properties[...]) and a selling_plan ID where applicable.

​
add_ons
object[]
required

Additional variants that must be added to the cart as separate line items (e.g. deposits, card authorisations)

​
available_item_count
integer
required

Number of available inventory items for the variant within the requested schedule