Storefront API reference

Product

Storefront Product API endpoints

Endpoints

GET/products
GET/products/{product_id}
GET/variants/{variant_id}
GET/plans/{plan_id}

Get list of products

GET /products

An API endpoint to get list of products with filtering options.

Query parameters

pageoptionalinteger

Page number for pagination

per_pageoptionalinteger

Entities per page

typeoptionalstring

Filter by product type

Possible values: one_time, subscription.

ids[]optionalinteger[]

Filter by product IDs

tags[]optionalstring[]

Filter by tag names

slugs[]optionalstring[]

Filter by product slugs

digitaloptionalboolean

Filter by digital products

gift_cardoptionalboolean

Filter by gift card products

sort[field]optionalstring

Field to sort by

Possible values: id, name.

sort[direction]optionalstring

Sort direction; defaults to asc.

Possible values: asc, desc.

Defaults to "asc".

Returnsobject

Products list response

Error responses

422object

A query parameter fails validation. tags holds a name that is not a tag of the shop; ids, tags or slugs is not an array or repeats a value; an ids entry is not an integer; a slug is longer than 80 characters; type is not one_time or subscription; digital or gift_card is not a boolean; sort is not an array, sort.field is missing or not id or name, or sort.direction is not asc or desc; page is below 1; per_page is outside 1-100; or expand is not an array.

curl https://api.subbly.co/storefront/v1/products \
  -H 'X-API-KEY: <api-key>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1,
      "bundle_id": 1,
      "bundle": {
        "id": 1,
        "name": "Bundle Name",
        "slug": "Bundle slug",
        "digital": false,
        "delivery_info": "delivery_info",
        "images": [
          {}
        ],
        "configurable": true,
        "description": "description",
        "hidden_items": true,
        "searchable": false,
        "show_ruleset_name": false,
        "quantity_selectors": [
          1
        ],
        "selection_type": "variant",
        "discount_type": "per_item",
        "price_type": "per_item",
        "ruleset_type": "total",
        "appearance_type": "one_step",
        "rulesets": [
          {}
        ],
        "plans": [
          {}
        ],
        "preferences": [
          {}
        ],
        "filters": [
          {}
        ],
        "discounts": [
          {}
        ],
        "change_product_collection_id": 1,
        "created_at": "2022-04-01T00:00:00.000000Z",
        "updated_at": "2022-04-01T00:00:00.000000Z"
      },
      "bundle_ruleset_id": 1,
      "bundle_ruleset": {
        "id": 1,
        "name": "Ruleset Name",
        "products": [
          {}
        ],
        "min_quantity": 1,
        "max_quantity": 2,
        "cta_text": "Add to cart",
        "created_at": "2022-04-01T00:00:00.000000Z",
        "updated_at": "2022-04-01T00:00:00.000000Z"
      },
      "slug": "yellow-t-shirt-with-pokemon-print",
      "type": "one_time",
      "name": "Yellow T-shirt with pokemon print",
      "description": "Yellow T-shirt with pokemon print",
      "delivery_info": "Free shipping on orders over $100",
      "collect_shipping_address": true,
      "gifting_enabled": true,
      "digital": false,
      "images": [
        {
          "id": 1,
          "url": "https://www.example.com/image.jpg",
          "order": 1,
          "created_at": "2022-04-01T00:00:00.000000Z",
          "updated_at": "2022-04-01T00:00:00.000000Z"
        }
      ],
      "metadata": [
        {
          "id": 1,
          "name": "Color",
          "slug": "color-red",
          "description": "description",
          "unit": "kg",
          "data_type": "single_line_string",
          "preset": true,
          "multiple": true,
          "variant": true,
          "save_behavior": "customer",
          "editable": true,
          "values": [
            {}
          ]
        }
      ],
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z",
      "gift_card": false,
      "gift_card_expiration": null,
      "variants": [
        {
          "id": 1,
          "bundle_plan_id": 1,
          "bundle_plan": {},
          "name": "Yellow T-shirt with pokemon print",
          "description": "Yellow T-shirt with pokemon print",
          "price": 799,
          "price_schema": {},
          "stock_count": 100,
          "parent": {},
          "product": {},
          "metadata": [
            {}
          ],
          "attributes": [
            {}
          ],
          "options": [
            {}
          ],
          "created_at": "2022-04-01T00:00:00.000000Z",
          "updated_at": "2022-04-01T00:00:00.000000Z"
        }
      ],
      "options": [
        {
          "id": 1,
          "name": "Size",
          "values": [
            "Medium"
          ]
        }
      ]
    }
  ]
}

Get product by ID

GET /products/{product_id}

A detailed description of the product.

Path parameters

product_idRequiredinteger

Product ID

ReturnsOneTimeProduct | SubscriptionProduct

Product object response

Error responses

400object

The product belongs to another shop, is not published, is archived, or is a variant or plan (it has a parent product).

404object

No product with this ID exists.

422object

expand is not an array.

curl https://api.subbly.co/storefront/v1/products/{product_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "bundle_id": 1,
  "bundle": {
    "id": 1,
    "name": "Bundle Name",
    "slug": "Bundle slug",
    "digital": false,
    "delivery_info": "delivery_info",
    "images": [
      {}
    ],
    "configurable": true,
    "description": "description",
    "hidden_items": true,
    "searchable": false,
    "show_ruleset_name": false,
    "quantity_selectors": [
      1
    ],
    "selection_type": "variant",
    "discount_type": "per_item",
    "price_type": "per_item",
    "ruleset_type": "total",
    "appearance_type": "one_step",
    "rulesets": [
      {}
    ],
    "plans": [
      {}
    ],
    "preferences": [
      {}
    ],
    "filters": [
      {}
    ],
    "discounts": [
      {}
    ],
    "change_product_collection_id": 1,
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "bundle_ruleset_id": 1,
  "bundle_ruleset": {
    "id": 1,
    "name": "Ruleset Name",
    "products": [
      {}
    ],
    "min_quantity": 1,
    "max_quantity": 2,
    "cta_text": "Add to cart",
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "slug": "yellow-t-shirt-with-pokemon-print",
  "type": "one_time",
  "name": "Yellow T-shirt with pokemon print",
  "description": "Yellow T-shirt with pokemon print",
  "delivery_info": "Free shipping on orders over $100",
  "collect_shipping_address": true,
  "gifting_enabled": true,
  "digital": false,
  "images": [
    {
      "id": 1,
      "url": "https://www.example.com/image.jpg",
      "order": 1,
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z"
    }
  ],
  "metadata": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01T00:00:00.000000Z",
  "updated_at": "2022-04-01T00:00:00.000000Z",
  "gift_card": false,
  "gift_card_expiration": null,
  "variants": [
    {
      "id": 1,
      "bundle_plan_id": 1,
      "bundle_plan": {},
      "name": "Yellow T-shirt with pokemon print",
      "description": "Yellow T-shirt with pokemon print",
      "price": 799,
      "price_schema": {},
      "stock_count": 100,
      "parent": {},
      "product": {},
      "metadata": [
        {}
      ],
      "attributes": [
        {}
      ],
      "options": [
        {}
      ],
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z"
    }
  ],
  "options": [
    {
      "id": 1,
      "name": "Size",
      "values": [
        "Medium"
      ]
    }
  ]
}

Get variant or pricing by ID

GET /variants/{variant_id}

A detailed description of the variant or pricing.

Path parameters

variant_idRequiredinteger

Variant or pricing ID

ReturnsVariant | Plan

Variant or pricing object response

Error responses

400object

The variant or plan belongs to another shop, is not published, is archived, or is a top-level product (it has no parent product).

404object

No product with this ID exists.

422object

expand is not an array.

curl https://api.subbly.co/storefront/v1/variants/{variant_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "bundle_plan_id": 1,
  "bundle_plan": {
    "id": 1,
    "pricing": {},
    "plan": {},
    "variant": {},
    "pricings": [
      {}
    ],
    "variants": [
      {}
    ],
    "prices": [
      {}
    ],
    "discounts": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "name": "Yellow T-shirt with pokemon print",
  "description": "Yellow T-shirt with pokemon print",
  "price": 799,
  "price_schema": {
    "i": 1,
    "type": "flat_price",
    "amount": 799,
    "ranges": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "stock_count": 100,
  "parent": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "gift_card": false,
    "gift_card_expiration": null,
    "variants": [
      {}
    ],
    "options": [
      {}
    ]
  },
  "product": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "gift_card": false,
    "gift_card_expiration": null,
    "variants": [
      {}
    ],
    "options": [
      {}
    ]
  },
  "metadata": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "attributes": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "options": [
    {
      "id": 1,
      "name": "Size",
      "value": "Medium"
    }
  ],
  "created_at": "2022-04-01T00:00:00.000000Z",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Get plan by ID

GET /plans/{plan_id}

A detailed description of the plan.

Path parameters

plan_idRequiredinteger

Plan ID

ReturnsPlan

Plan object response

Error responses

400object

The plan belongs to another shop, is not published, or is archived.

404object

No product with this ID exists, or the product is not a subscription product.

422object

expand is not an array.

curl https://api.subbly.co/storefront/v1/plans/{plan_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "parent": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "product": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "bundle_plan_id": 1,
  "bundle_plan": {
    "id": 1,
    "pricing": {},
    "plan": {},
    "variant": {},
    "pricings": [
      {}
    ],
    "variants": [
      {}
    ],
    "prices": [
      {}
    ],
    "discounts": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "name": "Yellow T-shirt with pokemon print",
  "pricing_name": "Yellow T-shirt with pokemon print",
  "description": "Yellow T-shirt with pokemon print",
  "price": 799,
  "price_schema": {
    "i": 1,
    "type": "flat_price",
    "amount": 799,
    "ranges": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "frequency_unit": "month",
  "frequency_count": 1,
  "plan_hash": "147405d250fb632a0063872d6651e12573245c7747db4e371fe8b231562b64cb",
  "anchored": true,
  "stock_count": 100,
  "trial_price": null,
  "trial_length": null,
  "trial_single_order": true,
  "charge_immediately": true,
  "ship_immediately": true,
  "rebilling_start_at": "2022-04-01",
  "cut_off_at": "2022-04-01",
  "cut_off_time": "00:00",
  "setup_fee": null,
  "pre_order_end_at": "2022-04-01",
  "shippings": [
    {
      "id": 1,
      "shipping_at": "2022-04-01T00:00:00.000000Z",
      "add_count": 1,
      "add_unit": "month",
      "unit_day": 1,
      "unit_offset": 0,
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z"
    }
  ],
  "survey": {
    "id": 1,
    "title": "What is your favorite color?",
    "questions": [
      {}
    ],
    "single_step": true,
    "multiply_price_by_shipment_number": true,
    "appearance_type": "after_checkout",
    "customizations": {},
    "created_at": "2023-03-30T15:00:00+00:00",
    "updated_at": "2023-03-30T15:00:00+00:00"
  },
  "metadata": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "commitment_billing_count": 0,
  "charges_limit": 0,
  "created_at": "2022-04-01T00:00:00.000000Z"
}

Product

Storefront Product API endpoints

Endpoints

GET/products
GET/products/{product_id}
GET/variants/{variant_id}
GET/plans/{plan_id}

Get list of products

GET /products

An API endpoint to get list of products with filtering options.

Query parameters

pageoptionalinteger

Page number for pagination

per_pageoptionalinteger

Entities per page

typeoptionalstring

Filter by product type

Possible values: one_time, subscription.

ids[]optionalinteger[]

Filter by product IDs

tags[]optionalstring[]

Filter by tag names

slugs[]optionalstring[]

Filter by product slugs

digitaloptionalboolean

Filter by digital products

gift_cardoptionalboolean

Filter by gift card products

sort[field]optionalstring

Field to sort by

Possible values: id, name.

sort[direction]optionalstring

Sort direction; defaults to asc.

Possible values: asc, desc.

Defaults to "asc".

Returnsobject

Products list response

paginationobject

data(OneTimeProduct | SubscriptionProduct)[]

Error responses

422object

curl https://api.subbly.co/storefront/v1/products \
  -H 'X-API-KEY: <api-key>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1,
      "bundle_id": 1,
      "bundle": {
        "id": 1,
        "name": "Bundle Name",
        "slug": "Bundle slug",
        "digital": false,
        "delivery_info": "delivery_info",
        "images": [
          {}
        ],
        "configurable": true,
        "description": "description",
        "hidden_items": true,
        "searchable": false,
        "show_ruleset_name": false,
        "quantity_selectors": [
          1
        ],
        "selection_type": "variant",
        "discount_type": "per_item",
        "price_type": "per_item",
        "ruleset_type": "total",
        "appearance_type": "one_step",
        "rulesets": [
          {}
        ],
        "plans": [
          {}
        ],
        "preferences": [
          {}
        ],
        "filters": [
          {}
        ],
        "discounts": [
          {}
        ],
        "change_product_collection_id": 1,
        "created_at": "2022-04-01T00:00:00.000000Z",
        "updated_at": "2022-04-01T00:00:00.000000Z"
      },
      "bundle_ruleset_id": 1,
      "bundle_ruleset": {
        "id": 1,
        "name": "Ruleset Name",
        "products": [
          {}
        ],
        "min_quantity": 1,
        "max_quantity": 2,
        "cta_text": "Add to cart",
        "created_at": "2022-04-01T00:00:00.000000Z",
        "updated_at": "2022-04-01T00:00:00.000000Z"
      },
      "slug": "yellow-t-shirt-with-pokemon-print",
      "type": "one_time",
      "name": "Yellow T-shirt with pokemon print",
      "description": "Yellow T-shirt with pokemon print",
      "delivery_info": "Free shipping on orders over $100",
      "collect_shipping_address": true,
      "gifting_enabled": true,
      "digital": false,
      "images": [
        {
          "id": 1,
          "url": "https://www.example.com/image.jpg",
          "order": 1,
          "created_at": "2022-04-01T00:00:00.000000Z",
          "updated_at": "2022-04-01T00:00:00.000000Z"
        }
      ],
      "metadata": [
        {
          "id": 1,
          "name": "Color",
          "slug": "color-red",
          "description": "description",
          "unit": "kg",
          "data_type": "single_line_string",
          "preset": true,
          "multiple": true,
          "variant": true,
          "save_behavior": "customer",
          "editable": true,
          "values": [
            {}
          ]
        }
      ],
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z",
      "gift_card": false,
      "gift_card_expiration": null,
      "variants": [
        {
          "id": 1,
          "bundle_plan_id": 1,
          "bundle_plan": {},
          "name": "Yellow T-shirt with pokemon print",
          "description": "Yellow T-shirt with pokemon print",
          "price": 799,
          "price_schema": {},
          "stock_count": 100,
          "parent": {},
          "product": {},
          "metadata": [
            {}
          ],
          "attributes": [
            {}
          ],
          "options": [
            {}
          ],
          "created_at": "2022-04-01T00:00:00.000000Z",
          "updated_at": "2022-04-01T00:00:00.000000Z"
        }
      ],
      "options": [
        {
          "id": 1,
          "name": "Size",
          "values": [
            "Medium"
          ]
        }
      ]
    }
  ]
}

Get product by ID

GET /products/{product_id}

A detailed description of the product.

Path parameters

product_idRequiredinteger

Product ID

ReturnsOneTimeProduct | SubscriptionProduct

Product object response

idinteger

bundle_idinteger | null

bundleBundle | null

Expandable link to the bundle.

bundle_ruleset_idinteger | null

bundle_rulesetBundleRuleset | null

Expandable link to the bundle ruleset.

slugstring

typestring

Possible values: one_time, subscription.

namestring

descriptionstring | null

delivery_infostring | null

collect_shipping_addressboolean

gifting_enabledboolean

digitalboolean

imagesProductImage[]

metadataEntityMetadata[] | null

Expandable list of metadata for the product.

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

gift_cardboolean

gift_card_expirationinteger | null

variantsVariant[] | null

Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.

optionsProductOptionGroup[] | null

List of all available options for this product.

Error responses

400object

The product belongs to another shop, is not published, is archived, or is a variant or plan (it has a parent product).

404object

No product with this ID exists.

422object

expand is not an array.

curl https://api.subbly.co/storefront/v1/products/{product_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "bundle_id": 1,
  "bundle": {
    "id": 1,
    "name": "Bundle Name",
    "slug": "Bundle slug",
    "digital": false,
    "delivery_info": "delivery_info",
    "images": [
      {}
    ],
    "configurable": true,
    "description": "description",
    "hidden_items": true,
    "searchable": false,
    "show_ruleset_name": false,
    "quantity_selectors": [
      1
    ],
    "selection_type": "variant",
    "discount_type": "per_item",
    "price_type": "per_item",
    "ruleset_type": "total",
    "appearance_type": "one_step",
    "rulesets": [
      {}
    ],
    "plans": [
      {}
    ],
    "preferences": [
      {}
    ],
    "filters": [
      {}
    ],
    "discounts": [
      {}
    ],
    "change_product_collection_id": 1,
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "bundle_ruleset_id": 1,
  "bundle_ruleset": {
    "id": 1,
    "name": "Ruleset Name",
    "products": [
      {}
    ],
    "min_quantity": 1,
    "max_quantity": 2,
    "cta_text": "Add to cart",
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "slug": "yellow-t-shirt-with-pokemon-print",
  "type": "one_time",
  "name": "Yellow T-shirt with pokemon print",
  "description": "Yellow T-shirt with pokemon print",
  "delivery_info": "Free shipping on orders over $100",
  "collect_shipping_address": true,
  "gifting_enabled": true,
  "digital": false,
  "images": [
    {
      "id": 1,
      "url": "https://www.example.com/image.jpg",
      "order": 1,
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z"
    }
  ],
  "metadata": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01T00:00:00.000000Z",
  "updated_at": "2022-04-01T00:00:00.000000Z",
  "gift_card": false,
  "gift_card_expiration": null,
  "variants": [
    {
      "id": 1,
      "bundle_plan_id": 1,
      "bundle_plan": {},
      "name": "Yellow T-shirt with pokemon print",
      "description": "Yellow T-shirt with pokemon print",
      "price": 799,
      "price_schema": {},
      "stock_count": 100,
      "parent": {},
      "product": {},
      "metadata": [
        {}
      ],
      "attributes": [
        {}
      ],
      "options": [
        {}
      ],
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z"
    }
  ],
  "options": [
    {
      "id": 1,
      "name": "Size",
      "values": [
        "Medium"
      ]
    }
  ]
}

Get variant or pricing by ID

GET /variants/{variant_id}

A detailed description of the variant or pricing.

Path parameters

variant_idRequiredinteger

Variant or pricing ID

ReturnsVariant | Plan

Variant or pricing object response

idinteger

bundle_plan_idinteger | null

bundle_planBundlePlan

namestring

descriptionstring | null

priceinteger

price_schemaPriceSchema

stock_countinteger | null

parentOneTimeProduct | nullDeprecated

Expandable link to the parent product. Use 'product' instead.

productOneTimeProduct | null

Expandable link to the parent product.

metadataEntityMetadata[]

attributesEntityMetadata[]Deprecated

optionsProductOption[]

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

Error responses

400object

The variant or plan belongs to another shop, is not published, is archived, or is a top-level product (it has no parent product).

404object

No product with this ID exists.

422object

expand is not an array.

curl https://api.subbly.co/storefront/v1/variants/{variant_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "bundle_plan_id": 1,
  "bundle_plan": {
    "id": 1,
    "pricing": {},
    "plan": {},
    "variant": {},
    "pricings": [
      {}
    ],
    "variants": [
      {}
    ],
    "prices": [
      {}
    ],
    "discounts": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "name": "Yellow T-shirt with pokemon print",
  "description": "Yellow T-shirt with pokemon print",
  "price": 799,
  "price_schema": {
    "i": 1,
    "type": "flat_price",
    "amount": 799,
    "ranges": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "stock_count": 100,
  "parent": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "gift_card": false,
    "gift_card_expiration": null,
    "variants": [
      {}
    ],
    "options": [
      {}
    ]
  },
  "product": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "gift_card": false,
    "gift_card_expiration": null,
    "variants": [
      {}
    ],
    "options": [
      {}
    ]
  },
  "metadata": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "attributes": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "options": [
    {
      "id": 1,
      "name": "Size",
      "value": "Medium"
    }
  ],
  "created_at": "2022-04-01T00:00:00.000000Z",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Get plan by ID

GET /plans/{plan_id}

A detailed description of the plan.

Path parameters

plan_idRequiredinteger

Plan ID

ReturnsPlan

Plan object response

idinteger

parentSubscriptionProduct | nullDeprecated

Expandable link to the parent product. Use 'product' instead.

productSubscriptionProduct | null

Expandable link to the parent product.

bundle_plan_idinteger | null

bundle_planBundlePlan

namestring

pricing_namestring

descriptionstring | null

priceinteger

price_schemaPriceSchema

frequency_unitstring

Possible values: day, month, year.

frequency_countinteger

plan_hashstring | null

Fingerprint of what decides when and how the plan bills (frequency, rebilling day and anchor, cut-off, commitment, trial, shipping cycles, membership). Plans with the same hash bill alike and all of a subscription's items share one; the plans of one GET subscriptions/{subscription_id}/plans row carry the same hash. Null on one-time variants and parent products.

anchoredboolean

stock_countinteger | null

trial_priceinteger | null

trial_lengthinteger | null

trial_single_orderboolean

charge_immediatelyboolean

ship_immediatelyboolean

rebilling_start_atstring | null

Format: date.

cut_off_atstring | null

Format: date.

cut_off_timestring | null

setup_feeinteger | null

pre_order_end_atstring | null

Format: date.

shippingsProductShipping[]

surveySurvey | null

metadataEntityMetadata[] | null

commitment_billing_countinteger

charges_limitinteger | null

created_atstring

Format: date-time.

Error responses

400object

The plan belongs to another shop, is not published, or is archived.

404object

No product with this ID exists, or the product is not a subscription product.

422object

expand is not an array.

curl https://api.subbly.co/storefront/v1/plans/{plan_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "parent": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "product": {
    "id": 1,
    "bundle_id": 1,
    "bundle": {},
    "bundle_ruleset_id": 1,
    "bundle_ruleset": {},
    "slug": "yellow-t-shirt-with-pokemon-print",
    "type": "one_time",
    "name": "Yellow T-shirt with pokemon print",
    "description": "Yellow T-shirt with pokemon print",
    "delivery_info": "Free shipping on orders over $100",
    "collect_shipping_address": true,
    "gifting_enabled": true,
    "digital": false,
    "images": [
      {}
    ],
    "metadata": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "bundle_plan_id": 1,
  "bundle_plan": {
    "id": 1,
    "pricing": {},
    "plan": {},
    "variant": {},
    "pricings": [
      {}
    ],
    "variants": [
      {}
    ],
    "prices": [
      {}
    ],
    "discounts": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "name": "Yellow T-shirt with pokemon print",
  "pricing_name": "Yellow T-shirt with pokemon print",
  "description": "Yellow T-shirt with pokemon print",
  "price": 799,
  "price_schema": {
    "i": 1,
    "type": "flat_price",
    "amount": 799,
    "ranges": [
      {}
    ],
    "created_at": "2022-04-01T00:00:00.000000Z",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  },
  "frequency_unit": "month",
  "frequency_count": 1,
  "plan_hash": "147405d250fb632a0063872d6651e12573245c7747db4e371fe8b231562b64cb",
  "anchored": true,
  "stock_count": 100,
  "trial_price": null,
  "trial_length": null,
  "trial_single_order": true,
  "charge_immediately": true,
  "ship_immediately": true,
  "rebilling_start_at": "2022-04-01",
  "cut_off_at": "2022-04-01",
  "cut_off_time": "00:00",
  "setup_fee": null,
  "pre_order_end_at": "2022-04-01",
  "shippings": [
    {
      "id": 1,
      "shipping_at": "2022-04-01T00:00:00.000000Z",
      "add_count": 1,
      "add_unit": "month",
      "unit_day": 1,
      "unit_offset": 0,
      "created_at": "2022-04-01T00:00:00.000000Z",
      "updated_at": "2022-04-01T00:00:00.000000Z"
    }
  ],
  "survey": {
    "id": 1,
    "title": "What is your favorite color?",
    "questions": [
      {}
    ],
    "single_step": true,
    "multiply_price_by_shipment_number": true,
    "appearance_type": "after_checkout",
    "customizations": {},
    "created_at": "2023-03-30T15:00:00+00:00",
    "updated_at": "2023-03-30T15:00:00+00:00"
  },
  "metadata": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "variant": true,
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {}
      ]
    }
  ],
  "commitment_billing_count": 0,
  "charges_limit": 0,
  "created_at": "2022-04-01T00:00:00.000000Z"
}

idinteger

bundle_idinteger | null

bundleBundle | null

Expandable link to the bundle.

bundle_ruleset_idinteger | null

bundle_rulesetBundleRuleset | null

Expandable link to the bundle ruleset.

slugstring

typestring

Possible values: one_time, subscription.

namestring

descriptionstring | null

delivery_infostring | null

collect_shipping_addressboolean

gifting_enabledboolean

digitalboolean

imagesProductImage[]

metadataEntityMetadata[] | null

Expandable list of metadata for the product.

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

gift_cardboolean

gift_card_expirationinteger | null

variantsVariant[] | null

Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.

optionsProductOptionGroup[] | null

List of all available options for this product.

idinteger

bundle_plan_idinteger | null

bundle_planBundlePlan

namestring

descriptionstring | null

priceinteger

price_schemaPriceSchema

stock_countinteger | null

parentOneTimeProduct | nullDeprecated

Expandable link to the parent product. Use 'product' instead.

productOneTimeProduct | null

Expandable link to the parent product.

metadataEntityMetadata[]

attributesEntityMetadata[]Deprecated

optionsProductOption[]

created_atstring

Format: date-time.

updated_atstring

Format: date-time.