SubblySubbly
Log inGet started
  • Get started
  • Developer resources
Private API reference
Docs
Information
    Base URLAuthenticationPaginationErrors
Customer
    Get list of customersCreate a customerGet customer by IDUpdate a customerDelete a customerChange a customer's store credit balanceCreate a customer noteUpdate a customer noteDelete a customer note
Address
    Create an addressUpdate an addressDelete an address
Pickup Info
    Get list of pickup infoCreate pickup infoUpdate pickup infoDelete pickup info
Subscription
    Get list of subscriptionsCreate a subscriptionGet subscription by IDUpdate a subscriptionCancel a subscriptionUndo cancellationPause a subscriptionResume a subscriptionSkip renewals until a dateReactivate a cancelled or expired subscriptionSwitch the subscription to another plan by starting overChange the plans of the subscription's itemsUpdate a subscription's shipping address and methodUpdate a subscription's payment methodUpdate a subscription's survey preferencesCreate a subscription itemShow a subscription itemUpdate a subscription itemRemove a subscription itemUpdate a subscription item's preferencesUpdate a subscription item's bundleChange the plan of a subscription itemChange the variant of a one-time itemApply a discount to a subscription itemRemove a subscription item discountApply a discount to a subscriptionRemove a subscription discount
Invoice
    Get list of invoicesGet invoice by IDSchedule the next payment for invoiceVoid an invoiceForgive an invoiceMark an invoice as paid
Order
    Get list of ordersGet order by IDUpdate an orderShip an orderCancel an orderMark an order as pendingArchive an orderMark an order as a future shipmentSync order shipping items
Payment Method
    Create a payment methodGet payment method by IDDelete a payment method
Transaction
    Get list of transactionsGet transaction by ID
Cancellation
    Get shop cancellation reasonsAdd a cancellation reasonRename a cancellation reasonDelete a cancellation reason
Product
    Get list of productsGet product by IDGet variant by IDUpdate variantGet plan by IDUpdate planCreate subscription productUpdate subscription productPublish subscription productUnpublish subscription productArchive subscription productSync subscription product metadataCreate one-time productUpdate one-time productPublish one-time productUnpublish one-time productArchive one-time productSync one-time product metadataCreate variantArchive variantBatch create/update/archive variantsCreate planArchive plan
Survey
    Get survey by IDGet list of surveys
Bundle
    Get list of bundlesCreate a new bundleGet bundle by IDUpdate a bundleGet list of bundle itemsCreate a bundle itemBatch create bundle itemsGet bundle item by IDUpdate a bundle itemDelete a bundle itemGet list of bundle groupsPublish a bundleUnpublish a bundleArchive a bundleSync bundle metadataCreate a bundle planGet bundle plan by IDUpdate a bundle planArchive a bundle plan
Tag
    Get list of tags
Metafield
    Get shop's metafieldsCreate a new metadataUpdate the metadata
Funnel
    Get list of funnelsGet funnel by ID
Option
    Get list of options
Country
    Get list of countries
Inventory
    Get list of inventory itemsCreate a new inventory itemGet inventory item by IDUpdate an inventory itemArchive an inventory itemGet list of inventory groupsCreate a new inventory groupGet inventory group by IDUpdate an inventory group
Coupon
    Get list of couponsCreate a couponGet coupon by IDUpdate a couponArchive a coupon
Product Collection
    Get list of product collectionsCreate a product collectionGet product collection by IDUpdate a product collectionPublish a product collectionUnpublish a product collectionArchive a product collectionGet list of collection groups with itemsSync collection items
Webhook
    Get list of webhook endpointsCreate a webhook endpointGet webhook delivery statisticsGet a webhook endpointUpdate a webhook endpointDelete a webhook endpointRotate the signing secretSend a test eventGet webhook deliveriesGet a delivery with its attemptsRetry a delivery manuallyGet the webhook event logGet one event with its deliveries across endpointsGet the catalogue of subscribable event types
Email Unsubscribe
    Unsubscribe an email address from marketing mail
Team Member
    Get list of team membersAdd a team memberGet team member by IDUpdate a team memberRemove a team member
Shop Settings
    Update the shop settings
Shop Owner
    Update the shop owner
Referral Program
    Update the referral program
Gateway
    Get list of gatewaysGet gateway by ID

Shop Settings

Private Shop Settings API endpoints

Endpoints
  • PATCH/shop/settings

Update the shop settings

PATCH /shop/settings

Partially update the shop's settings: send only the groups and keys you want to change; every other value stays as it is. Lists are replaced whole. The response always holds every key. A request either saves every value it sends or none of them.

Request body

businessoptionalShopSettingsBusiness

The business behind the shop, as customers see it.

localizationoptionalShopSettingsLocalization

Where and how the shop trades.

gatewaysoptionalShopSettingsGateways

Payment gateway options.

taxoptionalShopSettingsTax

Tax on customer purchases.

storefrontoptionalShopSettingsStorefront

What customers can do at checkout and in the customer portal.

brandingoptionalShopSettingsBranding

How checkout and the customer portal look.

productsoptionalShopSettingsProducts

Product options.

renewalsoptionalShopSettingsRenewals

How subscriptions renew.

dunningoptionalShopSettingsDunning

What happens after a renewal payment fails.

analyticsoptionalShopSettingsAnalytics

How subscription analytics count. They change the numbers only on shops with advanced analytics.

teamoptionalShopSettingsTeam

The shop's team.

trackingoptionalShopSettingsTracking

Conversion tracking.

ReturnsShopSettings

Shop settings object response

Error responses

422object

Validation failed: a value has the wrong type or is out of range, null was sent for a key that does not accept it, Stripe rejected business.vat_number, a VAT number was sent for a shop that will not trade in the UK or the EU, localization.trade_country_code changed after a customer placed an order or started a subscription, team two-factor authentication was turned on while a team member has no phone number, or the value needs a feature the shop's Subbly plan doesn't include.

curl -X PATCH https://api.subbly.co/private/v1/shop/settings \ -H 'X-API-KEY: <api-key>' \ -H 'Content-Type: application/json' \ -d '{ "storefront": { "pause_enabled": true }, "dunning": { "reattempt_interval_days": [ 2, 5 ] } }'
Response
{ "business": { "name": "Bloom Box", "support_email": "help@shop.com", "support_url": "https://shop.com/support", "terms_and_conditions": "https://shop.com/terms", "vat_number": "GB123456789" }, "localization": { "timezone": "Europe/London", "trade_country_code": "GB", "currency_rounding": "up", "weight_unit": "kg", "dimension_unit": "cm" }, "gateways": { "create_orders_for_pending_invoices": false, "stripe": {} }, "tax": { "enabled": false, "inclusive": false, "digital_shop_address_fallback": false }, "storefront": { "collect_billing_address": true, "collect_buyer_name": false, "collect_company_name": false, "collect_gift_recipient_email": false, "phone_number_optional": true, "tos_consent_required": true, "marketing_consent_required": false, "coupon_discount_enabled": true, "gift_card_discount_enabled": true, "coupon_and_referral_exclusive": false, "gift_card_skips_payment_method": false, "apply_balance_discount_to_all_items": false, "zero_charge_notice_enabled": false, "display_commitment_and_trial": true, "multiple_subscriptions_enabled": false, "subscription_start_date_enabled": false, "subscription_quantity_enabled": false, "subscription_plan_change": false, "auto_extend_commitment": false, "gift_duration_enabled": true, "gift_start_date_enabled": true, "skipping_enabled": true, "skipping_min_payments": 0, "skipping_max_cycles": 4, "prolong_subscription_skipping_enabled": false, "pause_enabled": true, "subscription_resume_date_enabled": false, "reactivation_enabled": false, "reactivation_charges_immediately": false, "cancellation_request_enabled": true, "cancellation_type": "immediate", "update_orders_address_enabled": false, "update_orders_preferences_enabled": false, "last_payment_method_removal_enabled": false }, "branding": { "brand_color": "#2f6b4f", "logo_url": "https://cdn.filestackcontent.com/AbC123", "favicon_url": "https://cdn.filestackcontent.com/DeF456" }, "products": { "out_of_stock_enabled": false }, "renewals": { "carry_late_orders_to_next_period": true, "align_billing_date_to_plan": false, "renewal_time": "00:00", "upcoming_renewal_notice_days": 3, "renew_out_of_stock_products": true, "substitute_out_of_stock_bundle_items": true, "auto_expire_action": "expire", "auto_expire_commitment_ending": "end_of_period", "survey_from_subscription": true }, "dunning": { "provider": "subbly", "reattempt_interval_days": [ 1, 3, 3, 3, 5 ], "cancel_subscription_if_unsuccessful": true }, "analytics": { "mrr_cancel_rule": "period_end", "mrr_dunning_grace_days": 30, "pause_lapse_days": 60, "include_shipping": true }, "team": { "two_factor_required": false }, "tracking": { "conversion_code": "<img src=\"https://pixel.example/conversion\">" } }
nameoptionalstring

Shop name customers see at checkout, in the customer portal and in emails. Cannot be null.

support_emailoptionalstring | null

Support email shown to customers. null removes it.

Format: email.

support_urloptionalstring | null

Link to the support page, shown in the customer portal. null removes it.

Format: uri.

terms_and_conditionsoptionalstring | null

Link to the terms and conditions, shown at checkout. null removes it.

Format: uri.

vat_numberoptionalstring | null

The merchant's own VAT number, used for the Subbly bill and shown on customer receipts. It can be set only while the trade country after this request is the United Kingdom or an EU country. Stripe checks a new number on save: a rejected number fails the whole request, and the response holds the number as Stripe formats it. With a valid number an EU merchant is not charged VAT on Subbly fees; UK merchants are. A trade country change keeps the number. null removes it.

timezoneoptionalstring

Shop timezone, as an IANA identifier. Renewal times and dates use it. Cannot be null.

trade_country_codeoptionalstring

Country of trade, as an uppercase two-letter code: usually where the customers are, while the business can be elsewhere. It decides the base currency, the domestic shipping country and whether business.vat_number can be set, and it can change only until a customer places an order or starts a subscription. A change moves the base currency to the country's currency, together with the primary card and PayPal gateways (an extra currency the shop already sold in is removed with its exchange rate and rounding), and makes a shipping rule cover the new country: the only rule moves when it covered just the old country, losing its excluded postcodes; otherwise a published rule with a free flat-price option is added. Cannot be null.

currency_roundingoptionalstring

How a converted price rounds to the currency's "Round to" value: up or nearest.

Possible values: up, nearest.

weight_unitoptionalstring

Unit of product weights.

Possible values: kg, g, lb, oz.

dimension_unitoptionalstring

Unit of product dimensions.

Possible values: cm, in.

create_orders_for_pending_invoicesoptionalboolean

With SEPA Debit, Bancontact and other payment methods that confirm later, orders are created before the payment is confirmed.

stripeoptionalShopSettingsStripe

Stripe checkout options.

enabledoptionalboolean

Tax is calculated on purchases.

inclusiveoptionalboolean

Prices include tax.

digital_shop_address_fallbackoptionalboolean

When a purchase of digital products only has no customer address, tax is worked out from the shop's address.

collect_billing_addressoptionalboolean

Checkout asks for a billing address.

collect_buyer_nameoptionalboolean

Gift checkout asks for the sender's first and last name.

collect_company_nameoptionalboolean

Address forms show a company name field.

collect_gift_recipient_emailoptionalboolean

Gift checkout asks for the recipient's email.

phone_number_optionaloptionalboolean

When true, checkout address forms don't ask for a phone number.

tos_consent_requiredoptionalboolean

Registration requires consent to the terms of service.

marketing_consent_requiredoptionalboolean

Checkout asks for explicit marketing consent.

coupon_discount_enabledoptionalboolean

Checkout shows the coupon field.

gift_card_discount_enabledoptionalboolean

Checkout shows the gift card field.

coupon_and_referral_exclusiveoptionalboolean

A coupon and a referral discount can't be used together.

gift_card_skips_payment_methodoptionalboolean

The payment method step is skipped when a gift card covers the whole amount.

apply_balance_discount_to_all_itemsoptionalboolean

When false, the customer's balance doesn't discount shipping, the setup fee, gift cards or trials. Applies at checkout and on renewals.

zero_charge_notice_enabledoptionalboolean

The payment step warns that a $0.00 charge confirmation may show.

display_commitment_and_trialoptionalboolean

Plan selection in cart and checkout shows the plan's commitment and trial.

multiple_subscriptions_enabledoptionalboolean

A customer can hold several subscriptions on the same plan. Multiple subscriptions are a feature of some Subbly plans (see Plans and limits in the developer docs), so on other plans only false is accepted.

subscription_start_date_enabledoptionalboolean

Customers choose the subscription start date at checkout.

subscription_quantity_enabledoptionalboolean

Customers set a subscription quantity in cart and checkout.

subscription_plan_changeoptionalboolean

Customers can change their subscription plan in the customer portal.

auto_extend_commitmentoptionalboolean

A completed commitment starts again for another term.

gift_duration_enabledoptionalboolean

Customers choose how long a gift subscription lasts.

gift_start_date_enabledoptionalboolean

Customers choose the gift start date.

skipping_enabledoptionalboolean

Customers can skip or pause their subscription in the customer portal.

skipping_min_paymentsoptionalinteger

Payments a subscription needs before the customer can skip or pause it. 0 means no minimum.

skipping_max_cyclesoptionalinteger

Most cycles a customer can skip at once. Changing it from 4 is a feature of some Subbly plans (see Plans and limits in the developer docs), so on other plans only 4 is accepted.

prolong_subscription_skipping_enabledoptionalboolean

Customers can extend a skip.

pause_enabledoptionalboolean

Customers can pause without a resume date.

subscription_resume_date_enabledoptionalboolean

Customers choose the date a skip or pause ends.

reactivation_enabledoptionalboolean

Customers can reactivate their own cancelled or expired subscription in the customer portal.

reactivation_charges_immediatelyoptionalboolean

A reactivation charges the customer right away instead of at a renewal date they pick.

cancellation_request_enabledoptionalboolean

A customer's cancellation becomes a request for the merchant to process; the subscription stays active until then.

cancellation_typeoptionalstring

When a customer's cancellation takes effect.

Possible values: immediate, end_of_period.

update_orders_address_enabledoptionalboolean

Customers can change the shipping address of their pending orders.

update_orders_preferences_enabledoptionalboolean

When a subscription's preferences change, its upcoming orders take on the new preferences.

last_payment_method_removal_enabledoptionalboolean

Customers can remove their last payment method.

brand_coloroptionalstring | null

Accent colour of checkout and the customer portal, as a hex colour (#RRGGBB or #RGB). null removes it, and the default colour is used.

logo_urloptionalstring | null

URL of the square logo in the checkout and customer portal headers. Upload the image elsewhere first. null removes it.

Format: uri.

favicon_urloptionalstring | null

URL of the browser tab icon on the checkout page. Upload the image elsewhere first. null removes it.

Format: uri.

out_of_stock_enabledoptionalboolean

Stock is checked, so products without enough stock can't be bought. Stock limits are a feature of some Subbly plans (see Plans and limits in the developer docs); on other plans this setting has no effect.

carry_late_orders_to_next_periodoptionalboolean

For subscriptions on a fixed shipping schedule: when the period's shipment date has already passed, the order moves to the next period.

align_billing_date_to_planoptionalboolean

For subscriptions on a fixed billing schedule: renewals keep to the plan's billing day, so a date moved off it is charged once and then returns to it.

renewal_timeoptionalstring

Time of day renewals run, as HH:mm in the shop timezone. Choosing the time is a feature of some Subbly plans (see Plans and limits in the developer docs), so on other plans only 00:00 is accepted. Cannot be null.

upcoming_renewal_notice_daysoptionalinteger

How many days before a renewal the upcoming-renewal email and event go out.

renew_out_of_stock_productsoptionalboolean

When false, a renewal with out-of-stock products is skipped instead of charged. Takes effect only while products.out_of_stock_enabled is true.

substitute_out_of_stock_bundle_itemsoptionalboolean

Out-of-stock bundle items are replaced with available ones on renewals. Takes effect only while products.out_of_stock_enabled is true.

auto_expire_actionoptionalstring

What happens when a subscription reaches its payment limit, or a gift its order limit: it expires or is cancelled.

Possible values: expire, cancel.

auto_expire_commitment_endingoptionalstring

When those subscriptions end: at the end of the last paid period, or right after the final payment.

Possible values: end_of_period, after_final_payment.

survey_from_subscriptionoptionalboolean

Renewals use the survey answers saved on the subscription, not the product's current survey.

provideroptionalstring

Who retries failed renewal payments: subbly, or the stunning or churn_buster app. Subbly's own retries run while the chosen app is not active. Cannot be null; send subbly instead.

Possible values: subbly, stunning, churn_buster.

reattempt_interval_daysoptionalinteger[]

Subbly's retries after a failed renewal: up to 5 waits in days, each counted from the previous failed attempt. [] means no retries. A request replaces the whole list; null is not accepted.

cancel_subscription_if_unsuccessfuloptionalboolean

After the last failed attempt the invoice is voided; when true, the subscription is cancelled too.

mrr_cancel_ruleoptionalstring

When a stopped subscription leaves MRR: at the end of its paid period, or on the day it is cancelled.

Possible values: period_end, cancel_day.

mrr_dunning_grace_daysoptionalinteger

Days an unpaid renewal stays in MRR.

pause_lapse_daysoptionalinteger | null

Days a pause lasts before it counts as churn. null means a pause never counts as churn.

include_shippingoptionalboolean

Shipping counts in revenue analytics.

two_factor_requiredoptionalboolean

Team members sign in to the Subbly admin with SMS two-factor authentication. Turning it on needs a phone number on every team member except the owner, otherwise it is a validation error; a change is copied onto every team member.

conversion_codeoptionalstring | null

The shop's conversion tracking code: HTML and scripts added to the page customers see after a purchase. It can use the purchase's details, such as the customer's name and email. null removes it.

businessShopSettingsBusiness

The business behind the shop, as customers see it.

localizationShopSettingsLocalization

Where and how the shop trades.

gatewaysShopSettingsGateways

Payment gateway options.

taxShopSettingsTax

Tax on customer purchases.

storefrontShopSettingsStorefront

What customers can do at checkout and in the customer portal.

brandingShopSettingsBranding

How checkout and the customer portal look.

productsShopSettingsProducts

Product options.

renewalsShopSettingsRenewals

How subscriptions renew.

dunningShopSettingsDunning

What happens after a renewal payment fails.

analyticsShopSettingsAnalytics

How subscription analytics count. They change the numbers only on shops with advanced analytics.

teamShopSettingsTeam

The shop's team.

trackingShopSettingsTracking

Conversion tracking.