Connecting your shop

Connect your shop to import its catalogue and bring paid orders into Bottle for delivery. Open Connections from your user menu and find the WooCommerce or Shopify tile. Your shop keeps responsibility for invoices, payments and refunds.

With WooCommerce you can also copy your website’s pages, blog posts, menus and pictures into Bottle Shop. See Copying your website.

WooCommerce: approve from your own WordPress

This is the quick way, with nothing to copy.

1. On the WooCommerce tile, choose How to connect.
2. Give the shop a name and enter its address, such as www.acmegas.co.uk. Bottle adds https:// if you leave it out. If WordPress is installed in a subfolder, include that folder, such as https://acmegas.co.uk/wordpress.
3. Leave Import new orders automatically on if you want paid orders to come into Bottle for delivery. Switch it off for catalogue access only.
4. Choose Connect with WooCommerce. Bottle sends you to your own WordPress.
5. Sign in if WordPress asks, then choose Approve.

WooCommerce makes a key for Bottle, hands it over itself, and sends you back to Connections with the shop in the list. If you choose Deny instead, nothing changes.

Automatic imports request Read/Write access because Bottle needs to create and manage its own order notifications, called webhooks. WooCommerce grants broad access with this permission; Bottle only uses remote writes for its own webhooks, not to change your products, prices, orders or payments. Catalogue-only approval requests Read access.

Already connected? In Orders from this shop, choose Approve in WordPress. Approve the extra access there without disconnecting your shop. Your existing product links and imported orders stay in place. Bottle starts setting up the notifications after approval; check for Receiving orders before relying on the feed.

Your shop must be reachable on https. WooCommerce refuses to hand a key to anything else, and Bottle will not connect to a shop over plain http either way.

If the shop shows “403 Request blocked”

This means the shop’s security firewall stopped the request before WordPress could handle it. Contact the person who manages the shop’s hosting. Give them the request ID and time shown on the error page, and explain that it happened while connecting Bottle to WooCommerce.

They should check which security rule blocked the WooCommerce approval page or API request and allow the legitimate connection. Do not switch off the firewall for the whole site. Pasting a key can avoid an approval-page problem, but it will not fix a firewall that also blocks the WooCommerce API.

WooCommerce: paste a key instead

If the approval page is switched off on your site, or you would rather make the key yourself:

1. In WordPress, open WooCommerce → Settings → Advanced → REST API and add a key named Bottle. Choose Read/Write for automatic order imports, or Read for catalogue imports only.
2. Copy the consumer key and secret. WordPress shows them once.
3. On the WooCommerce tile in Bottle, choose How to connect, then Paste a key instead.
4. Enter the shop’s name and address, paste both values, and choose Connect your shop.

If you already connected with a read-only key, Approve in WordPress is the simplest way to allow automatic imports. You can instead reconnect the same shop address with a Read/Write key. Bottle cannot widen a key’s permissions without your approval.

Shopify

Bottle currently connects Shopify using an Admin API access token that you provide. For an existing compatible app, enter your .myshopify.com address and token in Bottle. The app needs product-read permission (read_products) for its catalogue.

For automatic order imports, also provide that same app’s client secret. This is different from the access token: it lets Bottle verify that order notifications came from Shopify. The app needs order-read permission (read_orders) and access to the recipient details needed for delivery. If those details are unavailable, Bottle cannot safely import the order.

This connection does not install a Shopify app or renew expiring access tokens for you. If you do not already have suitable credentials, ask the person who manages your Shopify integration for help. Do not follow older instructions to create a new legacy custom app in Shopify’s admin: Shopify no longer supports that. Its existing-app guidance explains which credentials remain available.

Shopify normally allows access to the last 60 days of orders. Access to older orders needs Shopify’s additional approval; connecting the shop does not grant it.

Set up order imports

The Import new orders automatically preference starts switched on for a new connection. The switch alone does not finish setup or give Bottle permission to change your shop’s notification settings.

1. Pull catalogue first, so the products on shop orders are linked to products in Bottle.
2. On the shop’s card in Connections, find Orders from this shop.
3. Leave Import new orders automatically on. WooCommerce approval starts notification setup automatically; if extra permission is needed, choose Approve in WordPress. For Shopify or a manually pasted key, select Set up automatic orders.
4. Check that the status changes from Setup needed to Receiving orders. If setup fails after approval, check that your shop allows Bottle to create webhooks, or check the Shopify client secret, then choose Try setup again.

That explicit setup creates Bottle’s order notifications, often called webhooks. Once connected, Bottle reads the current order from the shop shortly after a notification arrives. Background checks help catch missed notifications, but delivery can be delayed if either service is unavailable. Check for orders now queues an extra check.

Imports start with new orders from the setup date; this is not a historical order import. Switching the preference off stops imports without disconnecting the catalogue. Existing Bottle orders remain.

Which orders come through

Bottle can create an order when it is fully paid, not already fulfilled, in pounds sterling, and its products are linked to this shop’s Bottle products. Delivery orders also need a usable UK name, address and postcode. A recognised yard collection can come through as a collection instead.

Bottle keeps the shop’s charged line prices, VAT and delivery charge. Explicit WooCommerce fees, such as a gas surcharge, come through separately when the items, fees, delivery and tax match the paid total. Bottle does not guess a fee from a difference in totals, replace prices with current catalogue prices or add cylinder deposits or rent that the shop did not charge. It also does not apply Bottle’s own surcharge rule: the customer has already checked out, so only the external shop’s actual charges are kept. Cancelled or already fulfilled orders are not created as new deliveries.

An imported order expects one empty back for each cylinder on it, as a refill swaps a full cylinder for an empty. A cylinder charge or purchase on the same order means the customer is keeping a new cylinder, so no empty is expected for it. When you mark the order delivered, Bottle asks how many empties came back and starts at that number. To put a count right afterwards, open the order, choose More actions, then Correct delivery. On a shop order you can correct the empties collected. What was delivered and paid for stays with your shop.

An imported order shows its shop reference, is already paid, and can be planned and delivered in Bottle. Bottle gives it a tracking reference and sends a delivery confirmation when the shop supplied an email address. The shop still sends its receipt and invoice; Bottle does not ask the customer to pay again.

When the customer already has an address at that postcode that reads the same, Bottle delivers to it and keeps its delivery hours, notes and pin. A different flat, floor or unit at the same postcode gets an address of its own.

Checking the import log

Choose Settings on the shop’s card in Connections, then Import log. An issue indicator beside the button means an order needs checking; the connection page does not expand into a long list of alerts.

Search by shop order number or ID, filter to Error, Needs review, Imported or Refunded, and use Previous and Next to move through the results. Open an order number to read what happened and see its recent results. An earlier failure stays in the history after a refund or a successful retry. Identical background checks are not repeated. When this log is first introduced, older orders start with their last saved result; earlier attempts were not retained.

Errors mean an import failed. Needs review means Bottle stopped before making a delivery change: for example, a product is not linked, a product is archived in Bottle, payment is incomplete or delivery details are missing. Each result explains what to check.

Resolve payment and refund issues in the shop, restore any archived product in Products, and check the product links or delivery details as needed. Then select Retry import to read the current order again. Retrying does not bypass the safety checks or automatically settle a refund.

Orders held only by their products come in by themselves once you restore the product or pull the catalogue. Those still held stay in Needs review.

While a paid shop order has not come into Bottle, Your day shows it under Needs attention. Choose See why to open Orders. At the top, each held order says what held it, with a button to sort it out: Restore an archived product, Link products for one that isn’t linked, or Try again.

Archiving a product your shop still sells holds every new shop order for it. Take it off sale in the shop as well, or keep it in Bottle.

Refunded orders

A fully refunded order is kept in Bottle as history, marked Refunded in shop. It is not new delivery work: Bottle does not move stock, raise an invoice, request payment or send a tracking email. You can read the original items and charges even if those products are no longer linked to Bottle. These records appear with cancelled orders, not orders waiting for delivery.

If the refund arrives after an order was planned, delivered or changed in Bottle, its financial status is recorded but its physical delivery and stock history are not reversed. The import log asks you to check any delivery that needs stopping. Part-refunded orders also need review so Bottle does not guess which items should still be delivered. Make the refund itself in the shop.

What Bottle reads

Catalogue pulls only read your shop. Order setup separately manages Bottle’s own notifications; Bottle does not push catalogue prices or stock changes back to the shop. From each published product it takes:

• the name, SKU and regular price (a sale price is not a price list);
• for WooCommerce, the product’s VAT rate from its tax class, including reduced and zero rates when that class has one clear rate;
• the weight, converted to kilograms whatever unit the shop counts in;
• the shop’s categories;
• the description with its formatting: paragraphs, headings, bold, italic, lists and links. Bottle takes the long description, or the short one when there is no long one. Anything else in it, such as embedded videos, pictures, scripts or styling, is left out. A description over 20,000 characters is not brought in, and the pull tells you which;
• the brand, from WooCommerce’s brand field or a “Brand” attribute, or Shopify’s vendor;
• the product’s pictures and the words saved with them, up to 12 a product;
• for a WooCommerce product sold in variations, one product per variation, named after the parent and the variation’s options, such as “Propane Cylinder Refill 13kg”, each with its own price, SKU and weight.

Some listings are not imported. The preview shows each one under Not imported, with what it is in your shop and what would let Bottle import it:

• External/Affiliate products, such as an “Enquire now” listing. These link to another page and have no price, so nobody can order them. To sell one in Bottle, make it a Simple product with a price in WooCommerce, then refresh the preview.
• Grouped products. These are a page showing other products together. Each product in the group is listed and imported on its own.
• Other WooCommerce product types, such as subscriptions or bookings. The preview names the type. Make the listing a Simple or Variable product to import it.
• Listings with no name or no price. Add the missing detail in your shop, then refresh the preview.
• Cylinder deposits and rent, when your import options leave them out. Turn on Cylinder deposits and rent under Change import options to include them.

Cylinders sold with an optional charge

Some WooCommerce shops sell a refill with an optional cylinder deposit or purchase charge. Bottle imports the refill at its own regular price and imports the charge separately. It does not add the optional charge to the refill price. More complicated kits or products with conditional options are left out for you to check, with a reason in the import results.

Listings clearly named as cylinder charges, deposits, purchases or rent are placed under Cylinder charges on the Products page, rather than among the goods you sell. This also works for clearly named Shopify listings. Pulling again can sort an earlier unclassified import without creating another copy. Products you have already classified, reviewed or put on Bottle Shop keep your settings.

Check each imported charge before using it. Bottle can suggest a gas type using the listing’s name, categories and description, with AI helping when available. The suggestion is not a billing instruction: charges remain unassigned until you approve their setup. Bottle does not invent a refund promise or rental period. One-off charges start with no automatic refund; check the refund terms before assigning them. Use the product review to adjust the suggested gas type, and open the charge to check its terms and which cylinders it applies to. A charge called “Small propane” and one called “Large propane” should not both be applied to every propane cylinder. Set size-specific charges in the charge editor instead of approving a whole-family assignment.

If a previous pull missed the refill products, choose Pull catalogue again after the import fix is available. There is no need to delete the existing catalogue or reconnect the shop.

Sterling only, for now

Catalogue imports need prices in pounds sterling. Bottle refuses a shop that sells in another currency rather than reading its prices as pounds.

Prices and VAT

Bottle keeps each price exactly as the shop quotes it, and records whether VAT is in that figure, so a shelf price of £39.99 stays £39.99. Most shops say whether their prices include VAT, and Bottle follows that.

If yours does not say, or says it wrong and you cannot change it over there, use Prices in this shop under the shop’s Settings in Connections, or beside the import button on Products, to choose for yourself:

• As the shop says (recommended): follow the shop. If the shop will not say, Bottle uses your own setting for how you enter prices, under Business settings → Your business → How you enter prices.
• Include VAT: read every price from this shop as including VAT.
• Exclude VAT: read every price from this shop as before VAT.

After each pull, Bottle says what it did, such as “Imported 25 products with prices including VAT, as your shop reports” or “following your VAT setting because the shop would not say”. For WooCommerce, Bottle also uses each product’s tax class to bring in its VAT rate. Pulling again corrects the rate on an already linked product if the tax class or its rate changed. If WooCommerce has different location-based rates for the same class, or the connection cannot read tax rates, Bottle leaves the existing rate alone rather than guessing. Check imported prices and rates before using them.

If VAT registration is off in Bottle, a price is simply the price. See VAT.

Pulling the catalogue

Choose Pull catalogue in Connections, or the import button under Shop catalogue on Products. Both open the same import window.

1. Choose what to include: Product pictures, Product descriptions, Cylinder deposits and rent, and Suggest product and gas types. All start switched on. Switching pictures or descriptions off does not delete any already in Bottle.
2. Leave Review gas types before applying checked. This is the default. If you deliberately switch it off, only confident cylinder matches to an existing gas type apply automatically. Charges and new gas types still need your approval.
3. Choose Preview products. Bottle reads the catalogue without changing products. Each row shows what will happen in Bottle: link to an existing product, add a product, update a product, or not imported, with the reason. Use Show to see one group at a time, with a count for each. Choose Read description to read a listing’s description.
4. Search the table and untick products you do not want. Select all applies across the whole preview, including other pages; searching does not change your selections.
5. Choose Import selected products. Only those products are added or updated. Your options are saved for next time. You can also choose Save these settings without importing anything.

If the shop catalogue or your existing Bottle products change after the preview, Bottle asks you to preview again before importing. If an import stops part-way through, refresh the preview and retry: already linked products are updated, not duplicated.

When suggestions are ready, the amber notice on Products tells you how many imported products need a look. Open Review to approve or adjust them. See Reviewing imported products.

Products are matched on the shop’s own ids, so importing again does not make duplicates. When a second shop sells products you already have, Bottle links them instead of adding them again. See Products on more than one shop.

A product takes the shop’s price when it is first pulled, and keeps its Bottle price afterwards: Bottle holds the rates agreed with particular customers, and the shop knows nothing about them. A weight the shop knows fills in a blank one, and never overwrites a weight somebody set in Bottle.

The brand fills in a blank the same way.

A description changed in your shop comes through on the next pull, as long as nobody has changed it in Bottle. Once you edit a description in Bottle, it is yours: later pulls leave it alone, and the pull tells you how many descriptions it kept. To take the shop’s version again, clear the description in Bottle, save, and pull.

Pictures

Bottle brings in each product’s pictures from your shop when you pull the catalogue. For a WooCommerce product sold in variations, each variation gets its own picture first and the parent’s pictures after it. Pictures already brought in are not copied again, so pulling twice is safe. A picture you remove in Bottle comes back on the next pull if it is still on the listing in your shop.

Each picture must be on a public https address, under 15 MB, and a real picture file. One that cannot be fetched is skipped, and the pull says how many were skipped and why. The rest of the pull carries on.

New goods arrive with Sell on Bottle Shop switched on, ready for your shop even if you have not set it up yet. This does not publish your shop itself. Cylinder charges and delivery fees stay off as standalone shop items. Later pulls keep each existing product’s switch as you set it, including products you have taken off sale. See Products and prices.

Bottle also sets recognised goods to a useful product type, such as Appliance, Accessory, Fuel or Consumable. When AI is available, it helps read the shop’s names, categories and descriptions. If the answer is uncertain, Bottle leaves it for review. You can change a product’s type in its details; later pulls keep your choice. Automatic product typing does not set gas types, cylinder swaps, deposits or rental terms.

Recognised gas products can also receive the Gas cylinder type automatically. By default they stay in review until you confirm which gas type they belong to. Switching off Review gas types before applying is an explicit choice to apply confident matches to existing gas types only; uncertain matches, new gas types and all charge assignments still need review.

More than one shop

You can connect as many WooCommerce and Shopify shops as you sell through, including two on the same platform. On the shop’s tile in Connections, choose Connect another shop and connect it the same way as the first.

Give each shop its own name, such as Main shop or Trade shop. The name is shown on every order from that shop, so it must be different from your other shops. To change it, choose Settings on the shop’s card, then Edit names and Save names. Orders already in Bottle show the new name.

Customers do not see that name. Their delivery emails and tracking page use your business name, and the Sender name from Customer emails still signs the emails. If a shop trades under a name of its own, fill in Name customers see under Edit names, or under Change beside the shop in Customer emails. Delivery emails for that shop’s orders then use it in the message, and the tracking page shows it. While Use this branding and sender for delivery and invoice emails too is on in Customer emails, it also replaces the sender name and the name at the top of those emails. Leave it blank to keep your business name and sender name. The card shows Customers see and the name once it is set. A shop can also send its emails from its own address. See Send a shop’s emails from its own address.

Each shop has its own card in Connections, with Pull catalogue and Settings. Settings holds that shop’s own options: Prices in this shop, what to include when you pull its catalogue, Import new orders automatically, its order notifications and its Import log. Changing one shop leaves the others as they are. Each shop’s orders come in through its own connection and are matched to its own products. They are marked delivered in that shop only. Two shops can use the same order number without mixing up their orders.

Whether you charge VAT is still set once for the business, in your tax settings. See Prices and VAT.

Products on more than one shop

Most businesses sell the same cylinders on each shop. Bottle keeps one product for each, linked to every shop that sells it, so stock, prices and reports stay in one place.

When you preview a second shop’s catalogue, each product that looks like one you already have shows Link to existing product and the product it links to. Bottle matches on the same SKU first, then the same name. For anything left, AI suggests a match when it is sure enough. Each row says how it was matched. Check suggested matches before you import.

If a match is wrong, or a product has none, click the product in its row and type part of a name or SKU to find the right one. To add it as a new product instead, choose Add as a new product. Each product can be linked to one listing per shop. A linked product keeps its Bottle price, and nothing else about it changes. Orders from the second shop then come in as that product.

If an order came in before its products were linked, it waits in the Import log as Needs review. Link the products and Bottle tries the order again.

The main shop

With two or more shops, one is the Main shop. Product names, descriptions, pictures and weights come from that shop. Pulling another shop keeps its links up to date and leaves the main shop’s details alone. A product only the other shop sells still takes its details from that shop.

Your first connected shop starts as the main shop. To change it, open another shop’s Settings and choose Make main shop. If you disconnect the main shop, the next connected shop becomes the main shop.

Who can do this

Signed-in owners, admins and people with the Technical role can connect shops, pull catalogues and manage order imports. Owners and admins review product and billing changes. Drivers, API keys and connected assistants cannot pull catalogues.

Disconnecting

To disconnect a shop, open its Settings and choose Disconnect. Disconnecting deletes the saved credentials and stops order imports. Imported products and orders stay, along with their shop references. Connecting the same shop address again keeps those links. To stop a key working on the WooCommerce side as well, remove it under WooCommerce → Settings → Advanced → REST API.

See Integrations on the Bottle website.