{
  "openapi": "3.1.0",
  "info": {
    "title": "Lowcart delivered price API",
    "version": "1.1.0",
    "description": "The real delivered total of a product at every Shopify store that ships to a country: item price, shipping, sales tax or VAT and import fees, read from each store's own checkout through Shopify's agent checkout (UCP) with a labelled sample address, no order placed. Every offer says where import duties are paid, and final totals rank first. Any product sold by Shopify stores. Free, no key, read only.",
    "contact": {
      "email": "hello@getlowcart.com",
      "url": "https://getlowcart.com/agents"
    },
    "termsOfService": "https://getlowcart.com/terms"
  },
  "servers": [
    {
      "url": "https://getlowcart.com"
    }
  ],
  "paths": {
    "/api/v1/price": {
      "get": {
        "operationId": "findDeliveredPrice",
        "summary": "Stores that deliver a product to a country, ranked by delivered total",
        "description": "Use before recommending or buying a product, to know what the shopper will really pay at each store and whether anything more is due at the door. A first check of a product can take up to about 10 seconds while store checkouts are read live; repeat checks within 6 hours are fast. Amazon, Daraz, Sephora and other marketplace links are read for the product name only.",
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": true,
            "description": "Brand plus product name, for example \"Anua Heartleaf 77% Soothing Toner 250ml\" or \"Stanley Quencher 40 oz\", or a product link. A bare type (\"toner\", \"headphones\") or a brand alone (\"COSRX\") is refused with a message asking for both.",
            "schema": {
              "type": "string",
              "maxLength": 300
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Two letter delivery country code, for example US, GB, AU, DE.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "postal_code",
            "in": "query",
            "required": false,
            "description": "Delivery ZIP or postcode, for shipping (and US and Canadian sales tax) to that exact area.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "US only: two letter state code, when no ZIP code is given.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked delivered totals",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing or unsupported product or country",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 15 checks in 10 minutes from one client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/import-fees": {
      "get": {
        "operationId": "importFeeRules",
        "summary": "Sales tax, VAT, GST and import duty on goods ordered from abroad",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Two letter country code: US, GB, AU, NZ or any EU country.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The rules, with the official source",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeeRules"
                }
              }
            }
          },
          "404": {
            "description": "Country not covered yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Offer": {
        "type": "object",
        "properties": {
          "store": {
            "type": "string"
          },
          "ships_from": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two letter country code"
          },
          "local": {
            "type": "boolean",
            "description": "The store ships from the delivery country"
          },
          "product": {
            "type": "string",
            "description": "The listing title at that store"
          },
          "total": {
            "type": "number",
            "description": "Delivered total in the response currency"
          },
          "currency": {
            "type": "string"
          },
          "local_total": {
            "type": [
              "number",
              "null"
            ]
          },
          "local_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "verified_at_checkout": {
            "type": "boolean",
            "description": "True when the total was read from the store's checkout"
          },
          "duties": {
            "type": "string",
            "enum": [
              "none",
              "included_in_price",
              "paid_at_checkout",
              "billed_at_door",
              "may_be_billed_at_door",
              "unknown_origin"
            ],
            "description": "Where import duties are paid. billed_at_door: estimated and included in total. may_be_billed_at_door: not included in total. unknown_origin: the store's shipping country is not known yet, import fees may apply if it ships from abroad."
          },
          "final_total": {
            "type": "boolean",
            "description": "False when an import bill may still be due at the door"
          },
          "shipping_option": {
            "type": [
              "string",
              "null"
            ]
          },
          "item_price": {
            "type": [
              "number",
              "null"
            ]
          },
          "shipping": {
            "type": [
              "number",
              "null"
            ]
          },
          "tax": {
            "type": [
              "number",
              "null"
            ]
          },
          "import_fees": {
            "type": [
              "number",
              "null"
            ],
            "description": "Null when unknown"
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "A discount code the checkout accepted"
          },
          "delivery_days": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer"
            }
          },
          "link": {
            "type": "string",
            "description": "Link to the product at that store"
          }
        }
      },
      "PriceResult": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "local_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "stores_checked": {
            "type": "integer"
          },
          "verified_at_checkout": {
            "type": "integer"
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            },
            "description": "Final totals first, cheapest first"
          },
          "unconfirmed": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Stores that sell the product but gave no confirmed total, with their item price"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": "string",
            "description": "The same answer as readable text"
          },
          "still_checking": {
            "type": "integer",
            "description": "Stores whose checkout was still answering; ask again in a minute for their totals"
          }
        }
      },
      "FeeRules": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string"
          },
          "local": {
            "type": "string"
          },
          "imports": {
            "type": "string"
          },
          "included": {
            "type": "string"
          },
          "source": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          },
          "reviewed": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}