{
    "openapi": "3.0.3",
    "info": {
        "title": "Storefront API",
        "version": "v1",
        "description": "Cart, shipping and checkout for your own storefront or a mobile app. A cart token identifies the buyer’s cart; the store’s own checkout runs on the same core, with the same rules and errors. Status: preview. Prices are integer minor units: 49000 means 490.00."
    },
    "servers": [
        {
            "url": "https://{store}/api/v1",
            "variables": {
                "store": {
                    "default": "your-store.storeforma.shop",
                    "description": "The store’s domain."
                }
            }
        }
    ],
    "security": [
        {
            "cartToken": []
        }
    ],
    "tags": [
        {
            "name": "Cart",
            "description": "A cart lives behind its token: create it once, then send X-Cart-Token with every call."
        },
        {
            "name": "Shipping",
            "description": "Shipping options for the cart’s address, then the carrier, city and branch for carrier methods (Nova Poshta, Ukrposhta)."
        },
        {
            "name": "Checkout",
            "description": "Place the order and send the buyer to the payment page."
        }
    ],
    "paths": {
        "/meta": {
            "get": {
                "operationId": "meta",
                "tags": [
                    "Cart"
                ],
                "summary": "API version",
                "description": "A quick check that the domain serves the Storefront API, and of its version.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "The API name and version.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "name": "Storeforma",
                                        "version": "v1"
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/carts": {
            "post": {
                "operationId": "create-cart",
                "tags": [
                    "Cart"
                ],
                "summary": "Create a cart",
                "description": "Creates an empty cart in the store’s currency and returns its token in meta.cart_token. Keep the token (for example in the app’s storage) and send it as X-Cart-Token with every other call.",
                "security": [],
                "responses": {
                    "201": {
                        "description": "The new cart and its token.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [],
                                        "totals": {
                                            "subtotal": 0,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 0
                                        },
                                        "shipping_option": null,
                                        "shipping_paid_by": null,
                                        "shipping_delivery": null
                                    },
                                    "meta": {
                                        "cart_token": "9f3c2a7e5b1d4c8a…"
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart": {
            "get": {
                "operationId": "show-cart",
                "tags": [
                    "Cart"
                ],
                "summary": "Get the cart",
                "description": "The cart with its lines, totals and the chosen delivery. Totals are recalculated on every read.",
                "responses": {
                    "200": {
                        "description": "The cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [
                                            {
                                                "id": "7",
                                                "purchasable_id": "15",
                                                "quantity": 1,
                                                "unit_price": 599900,
                                                "total": 599900
                                            }
                                        ],
                                        "totals": {
                                            "subtotal": 599900,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 599900
                                        },
                                        "shipping_option": "NOVA_POSHTA",
                                        "shipping_paid_by": "customer",
                                        "shipping_delivery": {
                                            "shipping_method_id": 1,
                                            "shipping_method_code": "NOVA_POSHTA",
                                            "shipping_method_name": "Нова пошта",
                                            "carrier": "nova_poshta",
                                            "carrier_name": "Нова пошта",
                                            "service_type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "city_name": "Київ",
                                            "delivery_point_name": "Відділення №12"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart/lines": {
            "post": {
                "operationId": "add-cart-line",
                "tags": [
                    "Cart"
                ],
                "summary": "Add a product",
                "description": "Adds a variant to the cart (purchasable_id is the variant id: offers[].id in the Integration API, or the variant on the product page). Adding the same variant again increases its quantity.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "purchasable_id",
                                    "quantity"
                                ],
                                "properties": {
                                    "purchasable_id": {
                                        "type": "integer",
                                        "description": "Variant id."
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "description": "From 1 to 100."
                                    },
                                    "input_options": {
                                        "type": "object",
                                        "description": "Options the shopper fills in, by key (the product's input_options in the Integration API): text, a choice value, true for a tick, a date as YYYY-MM-DD. A required option must be filled; the surcharge is the store's."
                                    }
                                }
                            },
                            "example": {
                                "purchasable_id": 15,
                                "quantity": 1,
                                "input_options": {
                                    "hraviiuvannia": "Для Ані"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [
                                            {
                                                "id": "7",
                                                "purchasable_id": "15",
                                                "quantity": 1,
                                                "unit_price": 599900,
                                                "total": 599900
                                            }
                                        ],
                                        "totals": {
                                            "subtotal": 599900,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 599900
                                        },
                                        "shipping_option": "NOVA_POSHTA",
                                        "shipping_paid_by": "customer",
                                        "shipping_delivery": {
                                            "shipping_method_id": 1,
                                            "shipping_method_code": "NOVA_POSHTA",
                                            "shipping_method_name": "Нова пошта",
                                            "carrier": "nova_poshta",
                                            "carrier_name": "Нова пошта",
                                            "service_type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "city_name": "Київ",
                                            "delivery_point_name": "Відділення №12"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Unknown variant, a quantity out of range or a required option not filled.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The selected purchasable id is invalid.",
                                    "errors": {
                                        "purchasable_id": [
                                            "The selected purchasable id is invalid."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart/lines/{line}": {
            "patch": {
                "operationId": "update-cart-line",
                "tags": [
                    "Cart"
                ],
                "summary": "Change a quantity",
                "description": "Sets the quantity of a cart line.",
                "parameters": [
                    {
                        "name": "line",
                        "in": "path",
                        "required": true,
                        "description": "Line id (lines[].id in the cart).",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 7
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "quantity"
                                ],
                                "properties": {
                                    "quantity": {
                                        "type": "integer",
                                        "description": "From 1 to 100."
                                    }
                                }
                            },
                            "example": {
                                "quantity": 2
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [
                                            {
                                                "id": "7",
                                                "purchasable_id": "15",
                                                "quantity": 1,
                                                "unit_price": 599900,
                                                "total": 599900
                                            }
                                        ],
                                        "totals": {
                                            "subtotal": 599900,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 599900
                                        },
                                        "shipping_option": "NOVA_POSHTA",
                                        "shipping_paid_by": "customer",
                                        "shipping_delivery": {
                                            "shipping_method_id": 1,
                                            "shipping_method_code": "NOVA_POSHTA",
                                            "shipping_method_name": "Нова пошта",
                                            "carrier": "nova_poshta",
                                            "carrier_name": "Нова пошта",
                                            "service_type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "city_name": "Київ",
                                            "delivery_point_name": "Відділення №12"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No such line in this cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Not Found"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "remove-cart-line",
                "tags": [
                    "Cart"
                ],
                "summary": "Remove a line",
                "description": "Removes a line from the cart.",
                "parameters": [
                    {
                        "name": "line",
                        "in": "path",
                        "required": true,
                        "description": "Line id.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 7
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Removed; no body."
                    },
                    "404": {
                        "description": "No such line in this cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Not Found"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart/addresses/{type}": {
            "put": {
                "operationId": "set-cart-address",
                "tags": [
                    "Cart"
                ],
                "summary": "Set an address",
                "description": "Sets the shipping or billing address. The shipping address decides the shipping options, so set it before asking for them. Without a billing address the shipping one is used at checkout.",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "description": "shipping or billing.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "shipping",
                                "billing"
                            ]
                        },
                        "example": "shipping"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "first_name",
                                    "last_name",
                                    "line_one",
                                    "city",
                                    "country_id"
                                ],
                                "properties": {
                                    "first_name": {
                                        "type": "string",
                                        "description": "Up to 120 characters."
                                    },
                                    "last_name": {
                                        "type": "string",
                                        "description": "Up to 120 characters."
                                    },
                                    "line_one": {
                                        "type": "string",
                                        "description": "Street and house. For a branch or pickup any short text; the branch fills the address."
                                    },
                                    "line_two": {
                                        "type": "string",
                                        "description": "Flat, floor."
                                    },
                                    "city": {
                                        "type": "string",
                                        "description": "City."
                                    },
                                    "postcode": {
                                        "type": "string",
                                        "description": "Postcode; needed for courier delivery."
                                    },
                                    "country_id": {
                                        "type": "integer",
                                        "description": "Country id in the store’s country list."
                                    },
                                    "contact_email": {
                                        "type": "string",
                                        "description": "Buyer e-mail; checkout needs it here or in its own field."
                                    },
                                    "contact_phone": {
                                        "type": "string",
                                        "description": "Buyer phone; required at checkout."
                                    },
                                    "delivery_instructions": {
                                        "type": "string",
                                        "description": "Note for the courier, up to 2000 characters."
                                    }
                                }
                            },
                            "example": {
                                "first_name": "Олена",
                                "last_name": "Коваль",
                                "line_one": "вул. Хрещатик, 1",
                                "city": "Київ",
                                "postcode": "01001",
                                "country_id": 1,
                                "contact_email": "olena@example.com",
                                "contact_phone": "+380671234567"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [
                                            {
                                                "id": "7",
                                                "purchasable_id": "15",
                                                "quantity": 1,
                                                "unit_price": 599900,
                                                "total": 599900
                                            }
                                        ],
                                        "totals": {
                                            "subtotal": 599900,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 599900
                                        },
                                        "shipping_option": "NOVA_POSHTA",
                                        "shipping_paid_by": "customer",
                                        "shipping_delivery": {
                                            "shipping_method_id": 1,
                                            "shipping_method_code": "NOVA_POSHTA",
                                            "shipping_method_name": "Нова пошта",
                                            "carrier": "nova_poshta",
                                            "carrier_name": "Нова пошта",
                                            "service_type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "city_name": "Київ",
                                            "delivery_point_name": "Відділення №12"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "A required field is missing.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The first name field is required.",
                                    "errors": {
                                        "first_name": [
                                            "The first name field is required."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart/shipping-options": {
            "get": {
                "operationId": "shipping-options",
                "tags": [
                    "Shipping"
                ],
                "summary": "List shipping options",
                "description": "Shipping methods available for the cart’s shipping address, with their price for this cart.\n\npaid_by tells who pays: store — the store pays and price is always 0; customer — the buyer pays price, or the carrier’s rates on delivery when price is 0.",
                "responses": {
                    "200": {
                        "description": "The options.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "identifier": "NOVA_POSHTA",
                                            "name": "Нова пошта",
                                            "description": "Відділення або поштомат",
                                            "price": 0,
                                            "currency": "UAH",
                                            "paid_by": "customer"
                                        },
                                        {
                                            "identifier": "PICKUP",
                                            "name": "Самовивіз",
                                            "description": "Київ, вул. Січових Стрільців, 21",
                                            "price": 0,
                                            "currency": "UAH",
                                            "paid_by": "store"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart/shipping-option": {
            "put": {
                "operationId": "choose-shipping-option",
                "tags": [
                    "Shipping"
                ],
                "summary": "Choose a shipping option",
                "description": "Chooses one of the shipping options. For a carrier method (Nova Poshta, Ukrposhta) choose the city and branch next with the delivery call; pickup and address delivery need nothing more.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "identifier"
                                ],
                                "properties": {
                                    "identifier": {
                                        "type": "string",
                                        "description": "identifier of an option."
                                    }
                                }
                            },
                            "example": {
                                "identifier": "NOVA_POSHTA"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [
                                            {
                                                "id": "7",
                                                "purchasable_id": "15",
                                                "quantity": 1,
                                                "unit_price": 599900,
                                                "total": 599900
                                            }
                                        ],
                                        "totals": {
                                            "subtotal": 599900,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 599900
                                        },
                                        "shipping_option": "NOVA_POSHTA",
                                        "shipping_paid_by": "customer",
                                        "shipping_delivery": {
                                            "shipping_method_id": 1,
                                            "shipping_method_code": "NOVA_POSHTA",
                                            "shipping_method_name": "Нова пошта",
                                            "carrier": "nova_poshta",
                                            "carrier_name": "Нова пошта",
                                            "service_type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "city_name": "Київ",
                                            "delivery_point_name": "Відділення №12"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The option is not available for this cart.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Цей спосіб доставки зараз недоступний.",
                                    "errors": {
                                        "identifier": [
                                            "Цей спосіб доставки зараз недоступний."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipping/carriers": {
            "get": {
                "operationId": "carriers",
                "tags": [
                    "Shipping"
                ],
                "summary": "List carriers",
                "description": "Carriers the store ships with, their services (branch, parcel_locker, courier…) and their shipping methods with who pays (store, customer, or threshold: the store from an order sum).",
                "responses": {
                    "200": {
                        "description": "The carriers.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "code": "nova_poshta",
                                            "name": "Нова пошта",
                                            "service_types": [
                                                "branch",
                                                "parcel_locker",
                                                "courier"
                                            ],
                                            "supports_shipments": true,
                                            "shipments_ready": true,
                                            "shipment_service_types": [
                                                "branch",
                                                "parcel_locker",
                                                "courier"
                                            ],
                                            "shipping_methods": [
                                                {
                                                    "code": "NOVA_POSHTA",
                                                    "name": "Нова пошта",
                                                    "description": "Відділення або поштомат",
                                                    "service_types": [
                                                        "branch",
                                                        "parcel_locker"
                                                    ],
                                                    "paid_by": "customer"
                                                }
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipping/cities": {
            "get": {
                "operationId": "cities",
                "tags": [
                    "Shipping"
                ],
                "summary": "Search cities",
                "description": "Cities from the carrier’s directory, by the start of the name. Up to 30.",
                "parameters": [
                    {
                        "name": "carrier",
                        "in": "query",
                        "required": true,
                        "description": "Carrier code from the carriers call.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "nova_poshta"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Start of the city name.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Київ"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Matching cities.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "name": "Київ",
                                            "label": "Київ, Київська обл."
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipping/delivery-points": {
            "get": {
                "operationId": "delivery-points",
                "tags": [
                    "Shipping"
                ],
                "summary": "Search branches and lockers",
                "description": "Branches or parcel lockers of the carrier in a city, by number or street.",
                "parameters": [
                    {
                        "name": "carrier",
                        "in": "query",
                        "required": true,
                        "description": "Carrier code.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "nova_poshta"
                    },
                    {
                        "name": "city_ref",
                        "in": "query",
                        "required": true,
                        "description": "ref of a city from the cities call.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "8d5a980d-391c-11dd-90d9-001a92567626"
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": true,
                        "description": "Service: branch or parcel_locker.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "branch",
                                "parcel_locker"
                            ]
                        },
                        "example": "branch"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Number or part of the address.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "12"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "From 1 to 40. Default 30.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 10
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Matching points.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "name": "Відділення №12",
                                            "number": "12",
                                            "type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "address": "вул. Князів Острозьких, 32/2",
                                            "postcode": "01010"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cart/shipping-delivery": {
            "put": {
                "operationId": "choose-delivery",
                "tags": [
                    "Shipping"
                ],
                "summary": "Choose the city and branch",
                "description": "For a carrier method: the city and, for a branch or locker, the point. The service is accepted only when the method allows it and the carrier’s directory has it in that city.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "shipping_method_code",
                                    "carrier",
                                    "service_type",
                                    "city_ref"
                                ],
                                "properties": {
                                    "shipping_method_code": {
                                        "type": "string",
                                        "description": "code of the method (shipping_methods in carriers)."
                                    },
                                    "carrier": {
                                        "type": "string",
                                        "description": "Carrier code."
                                    },
                                    "service_type": {
                                        "type": "string",
                                        "description": "branch, parcel_locker or courier."
                                    },
                                    "city_ref": {
                                        "type": "string",
                                        "description": "ref of the city."
                                    },
                                    "delivery_point_ref": {
                                        "type": "string",
                                        "description": "ref of the branch or locker; required for those services."
                                    }
                                }
                            },
                            "example": {
                                "shipping_method_code": "NOVA_POSHTA",
                                "carrier": "nova_poshta",
                                "service_type": "branch",
                                "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The cart with shipping_delivery filled.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "42",
                                        "currency": "UAH",
                                        "lines": [
                                            {
                                                "id": "7",
                                                "purchasable_id": "15",
                                                "quantity": 1,
                                                "unit_price": 599900,
                                                "total": 599900
                                            }
                                        ],
                                        "totals": {
                                            "subtotal": 599900,
                                            "shipping": 0,
                                            "tax": 0,
                                            "discount": 0,
                                            "total": 599900
                                        },
                                        "shipping_option": "NOVA_POSHTA",
                                        "shipping_paid_by": "customer",
                                        "shipping_delivery": {
                                            "shipping_method_id": 1,
                                            "shipping_method_code": "NOVA_POSHTA",
                                            "shipping_method_name": "Нова пошта",
                                            "carrier": "nova_poshta",
                                            "carrier_name": "Нова пошта",
                                            "service_type": "branch",
                                            "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
                                            "delivery_point_ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
                                            "city_name": "Київ",
                                            "delivery_point_name": "Відділення №12"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The carrier, service or point is not available.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Цей перевізник зараз недоступний.",
                                    "errors": {
                                        "carrier": [
                                            "Цей перевізник зараз недоступний."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/checkout": {
            "post": {
                "operationId": "checkout",
                "tags": [
                    "Checkout"
                ],
                "summary": "Place the order",
                "description": "Checks the whole cart again (stock, prices, delivery, the store’s rules) and places the order. Send the sums the buyer saw: when the cart changed meanwhile, the answer is 422 and nothing is charged.\n\nredirect_url is the payment provider’s page: send the buyer there; card data never passes through your app. It accepts payment for 30 minutes. Without redirect_url the order is already placed (cash on delivery, for example).\n\nThe same Idempotency-Key returns the same order instead of a second one, even after a dropped connection. A key used for another cart or sum answers 422 idempotency_key; use a new key for a new attempt.",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "A unique key for this attempt (a UUID). Repeating it returns the first response.",
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "expected_subtotal",
                                    "expected_total"
                                ],
                                "properties": {
                                    "expected_subtotal": {
                                        "type": "integer",
                                        "description": "Subtotal the buyer saw (totals.subtotal), minor units."
                                    },
                                    "expected_total": {
                                        "type": "integer",
                                        "description": "Total the buyer saw (totals.total), minor units."
                                    },
                                    "payment_driver": {
                                        "type": "string",
                                        "description": "Payment method; the store’s default when left out."
                                    },
                                    "payment_token": {
                                        "type": "string",
                                        "description": "Only for payment methods that need it."
                                    },
                                    "contact_email": {
                                        "type": "string",
                                        "description": "E-mail for the order; taken from the shipping address when left out."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "description": "Buyer’s comment, up to 1000 characters."
                                    },
                                    "marketing_opt_in": {
                                        "type": "boolean",
                                        "description": "true asks for a newsletter subscription (confirmed by e-mail)."
                                    }
                                }
                            },
                            "example": {
                                "expected_subtotal": 599900,
                                "expected_total": 599900,
                                "contact_email": "olena@example.com",
                                "notes": "Подзвоніть перед відправкою"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "The order; redirect_url when the buyer pays online.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "101",
                                        "reference": "2026-001045",
                                        "status": "awaiting-payment",
                                        "placed_at": null,
                                        "payment_driver": "app:com.storeforma.wayforpay",
                                        "redirect_url": "https://your-store.storeforma.shop/payments/8b1e…/start"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The cart changed, an item ran out, delivery is no longer available, or the key was used for another order.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Сума кошика змінилася.",
                                    "errors": {
                                        "checkout": [
                                            "Сума кошика змінилася. Перевірте кошик і спробуйте ще раз."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No X-Cart-Token, an expired token, or a cart that is already ordered.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "A valid X-Cart-Token header is required.",
                                    "errors": {
                                        "cart_token": [
                                            "Кошик не знайдено, строк доступу минув або його вже оформлено."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "cartToken": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Cart-Token",
                "description": "meta.cart_token from POST /carts."
            }
        },
        "schemas": {
            "ValidationError": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "errors": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        }
    }
}