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 });

Shipping destination

On stores using the new shipping settings, send the destination you sent to the Availability log as a logistics object, so the booked dates match the availability the customer saw.

Intent shipping to a postal code

{
  "variant_id": 123456789,
  "option": {
    "global_id": "gid://supercycle/CalendarRental::RentalPeriod/1",
    "params": { "rental_start": "2025-01-01" }
  },
  "logistics": {
    "delivery_method": {
      "destination": { "country_code": "CH", "postal_code": "1934" }
    }
  }
}

Add-ons

add_ons are extra variants to submit in the same /cart/add request as the cycle, in the format of Shopify’s Cart AJAX API. Include every add-on property except cart_quantity as items[n][property]:

Add-ons in the cart request

// A product add-on becomes:
// items[0][id] = 4321
// items[0][parent_id] = 123456789
// items[0][properties[For]] = "Evening gown"
intent.add_ons.forEach(({ cart_quantity, ...addOnAttributes }, index) => {
  Object.entries(addOnAttributes).forEach(([key, value]) => {
    formData.set(`items[${index}][${key}]`, value);
  });
});

Copy every property except cart_quantity. If you leave off parent_id, the add-on isn’t nested under the cycle. 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. Submit parent_id from the response. It’s the Shopify variant ID of the cycle. Shopify nests the add-on under that cart line and removes the add-on with the line. Deposits and card authorizations omit parent_id and stay separate lines. Shopify POS adds the add-on as its own line. Draft orders can’t nest a line, so the add-on stays separate there too. Send the cycle and the add-on in the same request, as the product form does. A later request is rejected with Cannot reference existing parent lines by variant_id, and the add-on isn’t added. properties[For] is the cycle product’s title, stored as a line item property on the add-on. When the same product is rented twice with the same add-on, each cycle gets its own add-on line.

Those two add-on lines can share a Shopify line key. Remove by line to remove one of them. Removing by key removes both.

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

logistics

object

Where the order will ship to. Optional. Only stores on the new shipping settings use it: the intent's dates go by the shipping rates that reach the destination.

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 to add in the same cart request as the cycle. Product add-ons include parent_id and nest under the cycle line. Deposits and card authorizations omit parent_id and stay separate lines.

Show child attributes

available_item_count

integer

required

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

​Shipping destination

​Add-ons

Path Parameters

Body

Response

Shipping destination

Add-ons