Skip to content
Bottle

Pull a shop's catalogue

POST
/shops/{id}/pull
curl --request POST \
  --url https://example.com/shops/019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f/pull \
  --header 'Content-Type: application/json' \
  --cookie __Host-bottle.session_token=<__Host-bottle.session_token> \
  --data '{ "settings": { "importImages": true, "importDescriptions": true, "importCylinderCharges": true, "suggestGasTypes": true, "reviewGasTypes": true }, "externalIds": [ "example" ], "previewHash": "example", "links": [ { "externalId": "example", "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ] }'

Creates what is new and updates what is already here, matched on the shop’s own id. Prices are taken for products this is the first sight of, and left alone afterwards: Bottle holds the rates agreed with particular customers and the shop knows nothing about them. Each price is kept exactly as the shop quotes it, flagged as including VAT or not: by the shop’s own setting, by the business’s pricesIncludeVat when the shop will not say, or by the priceBasis set on this connection. The response says which. Pictures come in through the same pipeline as uploaded ones. Each description comes in with its formatting (the long description, else the short one), sanitised, and replaces the one here only while nobody has changed that in Bottle since the last pull; descriptionsKept lists the products where the shop’s newer words were not taken. Listings sent in links are tied to a product already in Bottle instead of being added, and change nothing on it. When another shop is the main shop and also sells a product, this shop’s pull keeps its listing linked and leaves the product’s name, description, pictures, weight and maker to the main shop.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required

UUID v7

string format: uuid

Example 

019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f

UUID v7

Request Body

Section titled “Request Body”
Media typeapplication/json
object
settings
object
importImages
required
boolean
importDescriptions
required
boolean
importCylinderCharges
required
boolean
suggestGasTypes
required
boolean
reviewGasTypes
required
boolean
externalIds
Array<string>
<= 5000 items
previewHash
string
/^[a-f0-9]{64}$/
links
Array<object>
<= 5000 items
object
externalId
required
string
>= 1 characters <= 200 characters
productId
required

UUID v7

string format: uuid

Example 

019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f

Responses

Section titled “Responses”

200

Section titled “200”

What the pull did

Media typeapplication/json
object
shop
object
id
required

UUID v7

string format: uuid
source
required
string
Allowed values: woocommerce shopify
name
required
string
customerName
string | null
url
required
string
priceBasis
required

Shop: read the shop’s own setting (WooCommerce prices include tax, Shopify taxes included), and the business’s pricesIncludeVat when it will not say. inc: every price from this shop includes VAT. ex: none of them do.

string
Allowed values: shop inc ex
catalogueImportSettings
object
importImages
required
boolean
importDescriptions
required
boolean
importCylinderCharges
required
boolean
suggestGasTypes
required
boolean
reviewGasTypes
required
boolean
syncOrderCompletion
boolean
catalogueMain
boolean
importOrdersAutomatically
required
boolean
orderSyncStatus
required

Setup_required: order feed still needs authenticating; receiving: it has received or reconciled orders; error: the latest attempt failed; off: automatic order import is switched off.

string
Allowed values: setup_required receiving error off
orderSyncStartedAt
required
string | null format: date-time
lastOrderSyncAt
required
string | null format: date-time
lastOrderSyncError
required
string | null
lastPulledAt
required
string | null format: date-time
lastError
required
string | null
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
added
required
integer
updated
required
integer
linked
integer
skipped
required
Array<object>
object
externalId
required
string
reason
required
string
Allowed values: external grouped unknown_type composite_no_price composite_kit no_name no_price charges_excluded
productIds
required
Array<string>
pricesIncludedVat
required
boolean
priceBasisUsed
required
string
Allowed values: shop business
picturesAdded
required
integer
picturesFailed
required
Array<object>
object
productId
required

UUID v7

string format: uuid
url
required
string
reason
required
string
descriptionsKept
Array<string>
descriptionsTooLong
Array<string>

Example 

{
  "shop": {
    "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
    "source": "woocommerce",
    "name": "Main shop",
    "customerName": "Thameside Trade Gas",
    "url": "https://acmegas.co.uk",
    "priceBasis": "shop",
    "orderSyncStatus": "setup_required"
  },
  "skipped": [
    {
      "reason": "external"
    }
  ],
  "productIds": [
    "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
  ],
  "priceBasisUsed": "shop",
  "picturesFailed": [
    {
      "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
    }
  ],
  "descriptionsKept": [
    "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
  ],
  "descriptionsTooLong": [
    "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
  ]
}

401

Section titled “401”

Not signed in

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}

403

Section titled “403”

Not allowed to manage shops, or asking for a key to do it

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}

404

Section titled “404”

No such shop

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}

409

Section titled “409”

The catalogue changed after preview; review it again

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}

422

Section titled “422”

Validation failed

Media typeapplication/json
object
error
required
string
Allowed values: validation
message
required
string
issues
required
Array<object>
object
path
required
string
message
required
string

Example 

{
  "error": "validation",
  "issues": [
    {
      "path": "email",
      "message": "Invalid email"
    }
  ]
}

502

Section titled “502”

The shop could not be reached, or refused the credentials

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}