Intent - Supercycle

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
}

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 that turn a line item into a cycle when it’s added to the cart. Each method (calendar, subscription, membership, and resale) stores its options in a product metafield. Every option has a global_id, which is what you pass to this endpoint.

Metafield	Method
`product.metafields.supercycle.calendar_configuration`	Calendar
`product.metafields.supercycle.subscription_configuration`	Subscription
`product.metafields.supercycle.membership_configuration`	Membership
`product.metafields.supercycle.resale_configuration`	Resale

The options array in each metafield carries a global_id per option:

Calendar configuration

{
  "rental_periods": [
    { "global_id": "gid://supercycle/CalendarRental::RentalPeriod/1" },
    { "global_id": "gid://supercycle/CalendarRental::RentalPeriod/2" }
  ]
}

With the variant ID and the option’s global_id, call this endpoint to get the attributes to attach to the line item so Supercycle processes it as a cycle. The response attributes object is a set of key-value pairs to include when you submit the add-to-cart form. Add each one as a hidden input on the product form, or set it on the request body when you submit with 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 with 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 extra variants to submit in the same request, in the format of Shopify’s multiple items cart API. Include every add-on property except cart_quantity as items[n][property]:

Add-ons in the cart request

// One add-on becomes:
// 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 isn’t submitted. It’s the maximum total quantity of that variant that should be in the cart. Before you add the add-on, check the current cart and skip it 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

Show child attributes

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.

Show child attributes

add_ons

object[]

required

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

Show child attributes

available_item_count

integer

required

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

​Add-ons

Path Parameters

Body

Response

Add-ons