Subscription

Storefront Subscription API endpoints

Endpoints

GET/subscriptions
GET/subscriptions/{subscription_id}
PATCH/subscriptions/{subscription_id}
PATCH/subscriptions/{subscription_id}/preferences
PATCH/subscriptions/{subscription_id}/bundle
POST/subscriptions/{subscription_id}/cancel
DELETE/subscriptions/{subscription_id}/undo_cancellation
PATCH/subscriptions/{subscription_id}/payment_method
GET/subscriptions/{subscription_id}/shipping_methods
GET/subscriptions/{subscription_id}/local_pickups
POST/subscriptions/{subscription_id}/items
GET/subscriptions/{subscription_id}/items/{item_id}
PATCH/subscriptions/{subscription_id}/items/{item_id}
DELETE/subscriptions/{subscription_id}/items/{item_id}
PATCH/subscriptions/{subscription_id}/items/{item_id}/preferences
PATCH/subscriptions/{subscription_id}/items/{item_id}/bundle

Get list of subscriptions

GET /subscriptions

An API endpoint to get list of subscriptions.

Query parameters

pageoptionalinteger

Page

per_pageoptionalinteger

Entities per page

statusesoptionalstring[]

Filter by subscription status

Returnsobject

Subscriptions list response

paginationobject

dataSubscription[]

curl https://api.subbly.co/storefront/v1/subscriptions \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1,
      "customer_id": 1,
      "referred_by": 1,
      "product_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-01 00:00:00",
        "updated_at": "2022-04-01 00:00:00",
        "pricings": [
          {}
        ],
        "plans": [
          {}
        ],
        "change_product_collection_id": 1
      },
      "quantity": 1,
      "shipping_address_id": 1,
      "shipping_method_id": 1,
      "billing_address_id": 1,
      "payment_method_id": 1,
      "currency_code": "USD",
      "survey": {
        "version": 2,
        "survey_id": 1,
        "data": [
          {}
        ],
        "items_count": 1,
        "items": [
          {
            "id": 1,
            "product_id": 1,
            "survey_id": 1,
            "data": [
              {}
            ]
          }
        ]
      },
      "preferences": {
        "version": 2,
        "survey_id": 1,
        "data": [
          {}
        ],
        "items_count": 1,
        "items": [
          {
            "id": 1,
            "product_id": 1,
            "survey_id": 1,
            "data": [
              {}
            ]
          }
        ]
      },
      "bundle": {
        "preferences": [
          {}
        ],
        "items": [
          {}
        ]
      },
      "gift": {
        "message": "message",
        "starts_at": "2022-02-24 04:00:00",
        "order_limit": 1
      },
      "commitment_term_total_payments": 1,
      "cancel_at_end_of_commitment": true,
      "next_payment_date": "2023-04-23 00:45:00",
      "starts_at": "2023-04-23 00:45:00",
      "past_due": false,
      "next_shipment_at": "2023-04-23 00:45:00",
      "successful_charges_count": 1,
      "charges_limit": 1,
      "status": "active",
      "cancel_at_period_end": true,
      "cancellations": [
        {
          "id": 1,
          "subscription_id": 1,
          "reason": "reason",
          "start": "2023-04-23 00:45:00",
          "end": "2023-04-23 00:45:00",
          "extra_feedback": "extra_feedback",
          "reason_submitted_on": "2023-04-23 00:45:00",
          "created_at": "2022-04-01 00:00:00",
          "updated_at": "2022-04-01 00:00:00"
        }
      ],
      "discounts": [
        {
          "id": 1,
          "customer_id": 1,
          "amount_off": 1,
          "percent_off": 1,
          "coupon_id": 1,
          "coupon": {},
          "start": "2023-04-23 00:45:00",
          "end": "2023-04-23 00:45:00",
          "created_at": "2022-04-01 00:00:00",
          "updated_at": "2022-04-01 00:00:00"
        }
      ],
      "addons": [
        {
          "id": 1,
          "subscription_id": 1,
          "product_id": 1,
          "product": {},
          "duration": 1,
          "quantity": 1,
          "addon": true,
          "preferences": {},
          "bundle": {},
          "discounts": [
            {}
          ],
          "metadata": [
            {}
          ],
          "created_at": "2022-04-01 00:00:00",
          "updated_at": "2022-04-01 00:00:00"
        }
      ],
      "items": [
        {
          "id": 1,
          "subscription_id": 1,
          "product_id": 1,
          "product": {},
          "duration": 1,
          "quantity": 1,
          "addon": true,
          "preferences": {},
          "bundle": {},
          "discounts": [
            {}
          ],
          "metadata": [
            {}
          ],
          "created_at": "2022-04-01 00:00:00",
          "updated_at": "2022-04-01 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": [
            {}
          ]
        }
      ],
      "last_payment_at": "2023-04-23 00:45:00",
      "unpaid": false,
      "cancellation_requested": false,
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ]
}

Show subscription

GET /subscriptions/{subscription_id}

An api call to show the subscription.

Path parameters

subscription_idRequiredinteger

Subscription ID

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

Subscription survey preferences envelope. For subscriptions with multiple subscription items, items holds the per-item preferences and is authoritative; the top-level survey_id and data reflect the primary (first) subscription item only.

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl https://api.subbly.co/storefront/v1/subscriptions/{subscription_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update subscription

PATCH /subscriptions/{subscription_id}

An api call to update the subscription.

Path parameters

subscription_idRequiredinteger

Subscription ID

Request body

Update subscription

quantityoptionalintegerDeprecated

Subscription-level quantity. Rejected for subscriptions with multiple subscription items — update the quantity per item via PATCH /subscriptions/{subscription_id}/items/{item_id}.

metadataoptionalobject[] | null

List of metadata and their values

idRequiredinteger

Metadata ID

valuesRequiredobject[]

Array of metadata values

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "quantity": 1,
  "metadata": [
    {
      "id": 1,
      "values": [
        {
          "id": 10,
          "value": "Blue"
        }
      ]
    }
  ]
}'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update subscription survey preferences by Subscription ID

PATCH /subscriptions/{subscription_id}/preferences

Deprecated. Do not use it in new integrations.

Update the subscription survey preferences.

Deprecated. This endpoint operates on the subscription as a whole and is not available for subscriptions that have multiple subscription items — for those it responds with 410 Gone (error code endpoint_deprecated). Use PATCH /subscriptions/{subscription_id}/items/{item_id}/preferences instead.

Path parameters

subscription_idRequiredinteger

Subscription ID

Request body

Update subscription survey preferences

preferencesRequiredobject[]

question_idRequiredinteger

answersRequiredobject[]

update_ordersoptionalboolean

Update order preferences in the awaiting_delivery and future_shipment status. Allowed when the survey appearance type is after checkout, or when the sync_orders_preferences_on_subscription_update shop setting is enabled.

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

Error responses

410object

Endpoint deprecated for this subscription. Returned when the subscription has multiple subscription items — use the per-item preferences endpoint.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/preferences \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "preferences": [
    {
      "question_id": 1,
      "answers": [
        {
          "id": 1,
          "content": "content",
          "quantity": 1
        }
      ]
    }
  ],
  "update_orders": true
}'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update subscription bundle data by Subscription ID

PATCH /subscriptions/{subscription_id}/bundle

Update the subscription bundle data for a single-item subscription. Only applicable when the subscription has exactly one subscription item; for subscriptions with multiple subscription items update each item's bundle via PATCH /subscriptions/{subscription_id}/items/{item_id}/bundle.

Path parameters

subscription_idRequiredinteger

Subscription ID

Request body

Update subscription bundle data for a single-item subscription. Only applicable when the subscription has exactly one subscription item.

bundleRequiredSubscriptionBundleBody

Bundle payload for the subscription's single subscription item. Rejected for subscriptions that have multiple subscription items — update each item's bundle via PATCH /subscriptions/{subscription_id}/items/{item_id}/bundle.

preferencesRequiredBundlePreferenceBody[] | null

itemsRequiredBundleItemBody[]

quantityoptionalinteger | null

Subscription item quantity. Rejected for subscriptions with multiple subscription items — set the quantity per item instead.

product_idoptionalinteger | null

Target subscription product (a product change). Must share the current product's bundle or belong to its change-product collection.

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/bundle \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "bundle": {
    "preferences": [
      {
        "attribute_id": 1,
        "metafield_id": 1,
        "values": [
          null
        ]
      }
    ],
    "items": [
      {
        "product_id": 1,
        "quantity": 1
      }
    ]
  },
  "quantity": 1,
  "product_id": 1
}'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Cancel a subscription

POST /subscriptions/{subscription_id}/cancel

Cancels a subscription for a given reason.

Path parameters

subscription_idRequiredinteger

The ID of the subscription to cancel

Request body

Cancellation Reasons Body

reason_idoptionalinteger | null

The ID of the cancellation reason (available if cancellation reasons are enabled)

extra_feedbackoptionalstring | null

Additional feedback from the customer

typeoptionalstring | null

Optional cancellation type. Only 'end_of_period' is accepted. When omitted, committed subscriptions default to cancel at end of commitment; non-committed subscriptions cancel immediately.

Possible values: end_of_period.

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X POST https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/cancel \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason_id": 1,
  "extra_feedback": "extra_feedback",
  "type": "end_of_period"
}'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Undo cancellation

DELETE /subscriptions/{subscription_id}/undo_cancellation

Undo the cancellation of a subscription.

Path parameters

subscription_idRequiredinteger

The ID of the subscription

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X DELETE https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/undo_cancellation \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update subscription payment method

PATCH /subscriptions/{subscription_id}/payment_method

An api call to change the payment method the subscription is billed with. Only active subscriptions can be updated.

Path parameters

subscription_idRequiredinteger

Subscription ID

Request body

Update subscription payment method

payment_method_idRequiredinteger

ID of one of the customer payment methods. It has to belong to a gateway matching the live mode of the subscription.

currency_codeRequiredstring

Currency ISO code.

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/payment_method \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment_method_id": 567,
  "currency_code": "USD"
}'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Get shipping methods

GET /subscriptions/{subscription_id}/shipping_methods

Available shipping methods for the subscription when shipped to the given address. Dynamic carrier-rated methods are not returned, so service, carrier_id and carrier are always empty here and customs_fee and future_customs_fee are always 0. shipping_fee is priced from the subscription's current items, while future_shipping_fee is priced with no chargeable items, because the items of an existing subscription are billed by its renewal invoice.

Path parameters

subscription_idRequiredinteger

Subscription ID

Query parameters

address_idRequiredinteger

ID of one of the customer addresses the subscription would ship to. Returns an empty array when a pickup info ID is passed.

expand[]optionalstring[]

Expandable relations (e.g. carrier)

ReturnsCartShippingMethod[]

Array of shipping methods objects

idinteger

servicestring | null

Carrier service code. Only present for dynamic shipping methods.

carrier_idinteger | null

Shipping carrier ID. Only present for dynamic shipping methods.

carrierShippingCarrier | null

Expandable link to the shipping carrier. Only present for dynamic shipping methods.

typestring

Possible values: shipping_option, local_delivery, local_pickup.

methodShippingOption | LocalDelivery | LocalPickup

shipping_feeinteger

future_shipping_feeinteger

customs_feeinteger

Customs fee for the first shipment

Defaults to 0.

future_customs_feeinteger

Customs fee for recurring shipments

Defaults to 0.

prohibited_productsinteger[]

curl https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/shipping_methods \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

[
  {
    "id": 1,
    "service": "STANDARD",
    "carrier_id": 1,
    "carrier": {
      "id": 1,
      "name": "DHL",
      "service_codes": [
        "STANDARD",
        "EXPRESS"
      ]
    },
    "type": "shipping_option",
    "method": {
      "name": "US Free shipping method",
      "duration": "2-3 days",
      "type": "flat_price",
      "provider": "flavorcloud"
    },
    "shipping_fee": 10,
    "future_shipping_fee": 0,
    "customs_fee": 0,
    "future_customs_fee": 0,
    "prohibited_products": [
      1
    ]
  }
]

Get local pickups

GET /subscriptions/{subscription_id}/local_pickups

Available local pickups for the subscription. As on shipping_methods, service, carrier_id and carrier are always empty and customs_fee and future_customs_fee are always 0.

Path parameters

subscription_idRequiredinteger

Subscription ID

Query parameters

expand[]optionalstring[]

Expandable relations (e.g. carrier)

ReturnsCartShippingMethod[]

Array of local pickup objects

idinteger

servicestring | null

Carrier service code. Only present for dynamic shipping methods.

carrier_idinteger | null

Shipping carrier ID. Only present for dynamic shipping methods.

carrierShippingCarrier | null

Expandable link to the shipping carrier. Only present for dynamic shipping methods.

typestring

Possible values: shipping_option, local_delivery, local_pickup.

methodShippingOption | LocalDelivery | LocalPickup

shipping_feeinteger

future_shipping_feeinteger

customs_feeinteger

Customs fee for the first shipment

Defaults to 0.

future_customs_feeinteger

Customs fee for recurring shipments

Defaults to 0.

prohibited_productsinteger[]

curl https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/local_pickups \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

[
  {
    "id": 1,
    "service": "STANDARD",
    "carrier_id": 1,
    "carrier": {
      "id": 1,
      "name": "DHL",
      "service_codes": [
        "STANDARD",
        "EXPRESS"
      ]
    },
    "type": "shipping_option",
    "method": {
      "name": "US Free shipping method",
      "duration": "2-3 days",
      "type": "flat_price",
      "provider": "flavorcloud"
    },
    "shipping_fee": 10,
    "future_shipping_fee": 0,
    "customs_fee": 0,
    "future_customs_fee": 0,
    "prohibited_products": [
      1
    ]
  }
]

Create a subscription item

POST /subscriptions/{subscription_id}/items

Add a new item to a subscription. For subscription items the product must share the subscription's billing plan. The item is not charged immediately — it is billed on the next renewal.

Path parameters

subscription_idRequiredinteger

Subscription ID

Query parameters

expand[]optionalstring[]

List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)

Request body

Create a subscription item

typeRequiredstring

The item type. subscription adds another concurrent subscription line; one_time adds a one-time add-on product.

Possible values: one_time, subscription.

product_idRequiredinteger

The item's product id. For one_time items any valid one-time product is accepted. For subscription items the product must share the subscription's billing plan.

durationoptionalinteger | null

Optional add-on duration. Only valid when type is one_time; prohibited when type is subscription.

Possible values: 1.

quantityoptionalinteger

Item quantity. Defaults to 1. The maximum depends on the shop's subscription quantity-selector setting.

bundleoptionalSubscriptionBundleBody

Bundle configuration. Required when type is subscription and the item's product is a configurable bundle; must be omitted otherwise.

preferencesRequiredBundlePreferenceBody[] | null

itemsRequiredBundleItemBody[]

metadataoptionalobject[] | null

List of metadata and their values

idRequiredinteger

Metadata ID

valuesRequiredobject[]

Array of metadata values

ReturnsSubscriptionItem

Subscription item object response

idinteger

subscription_idinteger

product_idinteger

productVariant | null

Expandable link to the variant.

durationinteger | null

Possible values: 1.

quantityinteger

addonboolean

Whether this item is a one-time add-on (true) rather than a recurring subscription item (false).

preferencesSubscriptionItemPreferences

Survey preferences snapshot for a single subscription item.

bundleSubscriptionBundle | null

Bundle configuration for this item. null for one-time add-on items.

discountsDiscount[]

metadataEntityMetadata[] | null

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X POST https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/items \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "one_time",
  "product_id": 1,
  "duration": 1,
  "quantity": 1,
  "bundle": {
    "preferences": [
      {
        "attribute_id": 1,
        "metafield_id": 1,
        "values": [
          null
        ]
      }
    ],
    "items": [
      {
        "product_id": 1,
        "quantity": 1
      }
    ]
  },
  "metadata": [
    {
      "id": 1,
      "values": [
        {
          "id": 10,
          "value": "Blue"
        }
      ]
    }
  ]
}'

Response

{
  "id": 1,
  "subscription_id": 1,
  "product_id": 1,
  "product": {
    "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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  },
  "duration": 1,
  "quantity": 1,
  "addon": true,
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Show a subscription item

GET /subscriptions/{subscription_id}/items/{item_id}

Show a single subscription item.

Path parameters

subscription_idRequiredinteger

Subscription ID

item_idRequiredinteger

Subscription item ID

Query parameters

expand[]optionalstring[]

List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)

ReturnsSubscriptionItem

Subscription item object response

idinteger

subscription_idinteger

product_idinteger

productVariant | null

Expandable link to the variant.

durationinteger | null

Possible values: 1.

quantityinteger

addonboolean

Whether this item is a one-time add-on (true) rather than a recurring subscription item (false).

preferencesSubscriptionItemPreferences

Survey preferences snapshot for a single subscription item.

bundleSubscriptionBundle | null

Bundle configuration for this item. null for one-time add-on items.

discountsDiscount[]

metadataEntityMetadata[] | null

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/items/{item_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 1,
  "subscription_id": 1,
  "product_id": 1,
  "product": {
    "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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  },
  "duration": 1,
  "quantity": 1,
  "addon": true,
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update a subscription item

PATCH /subscriptions/{subscription_id}/items/{item_id}

Update a subscription item's quantity, duration, product and/or metadata. duration only applies to one_time items. product_id switches the item's product: for one_time items any one-time product is accepted; for subscription items the product must share the subscription's billing plan and must not be a configurable bundle (use the item bundle endpoint for configurable bundles).

Path parameters

subscription_idRequiredinteger

Subscription ID

item_idRequiredinteger

Subscription item ID

Query parameters

expand[]optionalstring[]

List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)

Request body

Update a subscription item

quantityoptionalinteger | null

Item quantity. When omitted the current quantity is kept.

durationoptionalinteger | null

Add-on duration. Only valid for one_time items; prohibited for subscription items. Set to 1 for a single shipment, or null to recur.

Possible values: 1.

product_idoptionalinteger

Switch the item's product. For one_time items any valid one-time product is accepted. For subscription items the product must share the subscription's billing plan and must not be a configurable bundle.

metadataoptionalobject[] | null

List of metadata and their values

idRequiredinteger

Metadata ID

valuesRequiredobject[]

Array of metadata values

ReturnsSubscriptionItem

Subscription item object response

idinteger

subscription_idinteger

product_idinteger

productVariant | null

Expandable link to the variant.

durationinteger | null

Possible values: 1.

quantityinteger

addonboolean

Whether this item is a one-time add-on (true) rather than a recurring subscription item (false).

preferencesSubscriptionItemPreferences

Survey preferences snapshot for a single subscription item.

bundleSubscriptionBundle | null

Bundle configuration for this item. null for one-time add-on items.

discountsDiscount[]

metadataEntityMetadata[] | null

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/items/{item_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "quantity": 1,
  "duration": 1,
  "product_id": 1,
  "metadata": [
    {
      "id": 1,
      "values": [
        {
          "id": 10,
          "value": "Blue"
        }
      ]
    }
  ]
}'

Response

{
  "id": 1,
  "subscription_id": 1,
  "product_id": 1,
  "product": {
    "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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  },
  "duration": 1,
  "quantity": 1,
  "addon": true,
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Remove a subscription item

DELETE /subscriptions/{subscription_id}/items/{item_id}

Remove a subscription item. The last remaining subscription item cannot be removed — the request responds with 400 (error code last_subscription_item); cancel the subscription instead.

This endpoint is concurrency limited to a single in-flight request per customer. Overlapping requests respond with 429 (error code too_many_requests) instead of queueing.

Path parameters

subscription_idRequiredinteger

Subscription ID

item_idRequiredinteger

Subscription item ID

Query parameters

expand[]optionalstring[]

List of relations to expand (e.g. product, items, discounts, metadata)

ReturnsSubscription

Subscription object response

idinteger

customer_idinteger

referred_byinteger | null

product_idinteger

productSubscriptionProduct | null

Expandable link to the product

quantityinteger | nullDeprecated

Deprecated. null for subscriptions with multiple subscription items. Use the per-item quantity on items[].

shipping_address_idinteger

shipping_method_idinteger

billing_address_idinteger

payment_method_idinteger

currency_codestring

surveySubscriptionPreferencesDeprecated

Deprecated. Alias of preferences.

preferencesSubscriptionPreferences

bundleSubscriptionBundleDeprecated

Deprecated. Empty for subscriptions with multiple subscription items. Use the per-item bundle on items[].

giftobject | null

commitment_term_total_paymentsinteger | null

cancel_at_end_of_commitmentboolean

next_payment_datestring

Format: date-time.

starts_atstring | null

Subscription start date, set when the customer chose a future start.

Format: date-time.

past_dueboolean

next_shipment_atstring | null

Format: date-time.

successful_charges_countinteger

Number of successful charges.

charges_limitinteger | null

statusstring

The current status of the subscription. Possible values:

active: The subscription is currently active, and the user is being billed as per the plan's terms
trial: The subscription is in a trial period, and will automatically switch to an active status with billing at the start of the next renewal cycle
pre_order: The subscription has been created but will only be charged once the pre-order end date is reached
gift_waiting_to_start: A subscription that was gifted and is set to begin at a future date
cancelled: The subscription has been canceled and will not renew at the end of the current billing period
switched: The subscription has been switched to a different plan with purpose to reset subscription's order count
expired: The subscription has ended due to reaching its auto expire cycles

Possible values: active, trial, pre_order, gift_waiting_to_start, cancelled, switched, expired.

cancel_at_period_endboolean

Whether the subscription is set to cancel at the end of the current billing period.

cancellationsCancellation[]

discountsDiscount[]

addonsSubscriptionItem[]Deprecated

Deprecated. Contains only the one-time items (legacy add-ons). Use items for the full list.

itemsSubscriptionItem[]

The subscription's items — recurring subscription items and any one-time add-on items.

metadataEntityMetadata[] | null

last_payment_atstring

Format: date-time.

unpaidboolean

cancellation_requestedboolean

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

Error responses

400object

The last remaining subscription item cannot be removed. Cancel the subscription instead.

429object

Too many concurrent requests. Only one removal may be in flight per customer at a time; retry once the previous request has completed.

curl -X DELETE https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/items/{item_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 1,
  "customer_id": 1,
  "referred_by": 1,
  "product_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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00",
    "pricings": [
      {}
    ],
    "plans": [
      {}
    ],
    "change_product_collection_id": 1
  },
  "quantity": 1,
  "shipping_address_id": 1,
  "shipping_method_id": 1,
  "billing_address_id": 1,
  "payment_method_id": 1,
  "currency_code": "USD",
  "survey": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ],
    "items_count": 1,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "survey_id": 1,
        "data": [
          {}
        ]
      }
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "gift": {
    "message": "message",
    "starts_at": "2022-02-24 04:00:00",
    "order_limit": 1
  },
  "commitment_term_total_payments": 1,
  "cancel_at_end_of_commitment": true,
  "next_payment_date": "2023-04-23 00:45:00",
  "starts_at": "2023-04-23 00:45:00",
  "past_due": false,
  "next_shipment_at": "2023-04-23 00:45:00",
  "successful_charges_count": 1,
  "charges_limit": 1,
  "status": "active",
  "cancel_at_period_end": true,
  "cancellations": [
    {
      "id": 1,
      "subscription_id": 1,
      "reason": "reason",
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "extra_feedback": "extra_feedback",
      "reason_submitted_on": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "addons": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 00:00:00"
    }
  ],
  "items": [
    {
      "id": 1,
      "subscription_id": 1,
      "product_id": 1,
      "product": {},
      "duration": 1,
      "quantity": 1,
      "addon": true,
      "preferences": {},
      "bundle": {},
      "discounts": [
        {}
      ],
      "metadata": [
        {}
      ],
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "last_payment_at": "2023-04-23 00:45:00",
  "unpaid": false,
  "cancellation_requested": false,
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update a subscription item's preferences

PATCH /subscriptions/{subscription_id}/items/{item_id}/preferences

Update the survey preferences (answers) for a single subscription item.

Path parameters

subscription_idRequiredinteger

Subscription ID

item_idRequiredinteger

Subscription item ID

Query parameters

expand[]optionalstring[]

List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)

Request body

Update a subscription item's survey preferences

preferencesRequiredobject[] | null

question_idRequiredinteger

answersRequiredobject[]

update_ordersoptionalboolean

ReturnsSubscriptionItem

Subscription item object response

idinteger

subscription_idinteger

product_idinteger

productVariant | null

Expandable link to the variant.

durationinteger | null

Possible values: 1.

quantityinteger

addonboolean

Whether this item is a one-time add-on (true) rather than a recurring subscription item (false).

preferencesSubscriptionItemPreferences

Survey preferences snapshot for a single subscription item.

bundleSubscriptionBundle | null

Bundle configuration for this item. null for one-time add-on items.

discountsDiscount[]

metadataEntityMetadata[] | null

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/items/{item_id}/preferences \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "preferences": [
    {
      "question_id": 1,
      "answers": [
        {
          "id": 1,
          "content": "content",
          "quantity": 1
        }
      ]
    }
  ],
  "update_orders": true
}'

Response

{
  "id": 1,
  "subscription_id": 1,
  "product_id": 1,
  "product": {
    "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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  },
  "duration": 1,
  "quantity": 1,
  "addon": true,
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

Update a subscription item's bundle

PATCH /subscriptions/{subscription_id}/items/{item_id}/bundle

Update the configurable-bundle configuration (preferences, items, quantity and optionally the product) of a single subscription item. The item's product must be a configurable bundle. Works for subscriptions with any number of subscription items.

Path parameters

subscription_idRequiredinteger

Subscription ID

item_idRequiredinteger

Subscription item ID

Query parameters

expand[]optionalstring[]

List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)

Request body

Update a single subscription item's configurable bundle. The item's product must be a configurable bundle.

bundleRequiredSubscriptionBundleBody

Bundle payload (preferences + items) for this subscription item.

preferencesRequiredBundlePreferenceBody[] | null

itemsRequiredBundleItemBody[]

quantityoptionalinteger

Item quantity. When omitted the current quantity is kept.

product_idoptionalinteger | null

Optional target product for this item. Must be one of the item's available products — i.e. share the subscription's plan (same billing cadence) and be a configurable bundle. When omitted the item keeps its current product.

ReturnsSubscriptionItem

Subscription item object response

idinteger

subscription_idinteger

product_idinteger

productVariant | null

Expandable link to the variant.

durationinteger | null

Possible values: 1.

quantityinteger

addonboolean

Whether this item is a one-time add-on (true) rather than a recurring subscription item (false).

preferencesSubscriptionItemPreferences

Survey preferences snapshot for a single subscription item.

bundleSubscriptionBundle | null

Bundle configuration for this item. null for one-time add-on items.

discountsDiscount[]

metadataEntityMetadata[] | null

created_atstring

Format: date-time.

updated_atstring

Format: date-time.

curl -X PATCH https://api.subbly.co/storefront/v1/subscriptions/{subscription_id}/items/{item_id}/bundle \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "bundle": {
    "preferences": [
      {
        "attribute_id": 1,
        "metafield_id": 1,
        "values": [
          null
        ]
      }
    ],
    "items": [
      {
        "product_id": 1,
        "quantity": 1
      }
    ]
  },
  "quantity": 1,
  "product_id": 1
}'

Response

{
  "id": 1,
  "subscription_id": 1,
  "product_id": 1,
  "product": {
    "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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  },
  "duration": 1,
  "quantity": 1,
  "addon": true,
  "preferences": {
    "version": 2,
    "survey_id": 1,
    "data": [
      {}
    ]
  },
  "bundle": {
    "preferences": [
      {}
    ],
    "items": [
      {}
    ]
  },
  "discounts": [
    {
      "id": 1,
      "customer_id": 1,
      "amount_off": 1,
      "percent_off": 1,
      "coupon_id": 1,
      "coupon": {},
      "start": "2023-04-23 00:45:00",
      "end": "2023-04-23 00:45:00",
      "created_at": "2022-04-01 00:00:00",
      "updated_at": "2022-04-01 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": [
        {}
      ]
    }
  ],
  "created_at": "2022-04-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}