{
  "openapi": "3.1.0",
  "info": {
    "title": "Scurri Delivery Options API",
    "contact": {
      "email": "support@scurri.com"
    },
    "version": "2025.1",
    "description": "The Delivery Options API provides eCommerce sellers with accurate shipping\noptions at the checkout. Rules are created in the Scurri UI which enables you\nto specify the criteria for which options appear at checkout - this includes\nattributes such as recipient address, item dimension, and weight, and the day\nof the week. The API is also integrated with:\n- Delivery Locations lookup: An API that provides eCommerce sellers with a list of delivery\n  locations available at checkout. This allows customers to deliver their package to a location convenient to them. \n- Estimated Delivery Date calculation: Provides the estimated delivery date,\n  when available.\n\n## Authentication\nAll requests must be authenticated using API token-based authentication.\nYou must include the token in the Authorization header, e.g.:\n``` \nAuthorization: token YOUR_API_TOKEN\n```\n\n## Request and Response Format\nAll requests and responses are in JSON format, unless stated otherwise.\n"
  },
  "servers": [
    {
      "url": "https://sandbox.scurri.co.uk",
      "description": "Scurri Sandbox Environment"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Delivery Options",
      "description": "This API provides a list of available delivery options, along with the service_id, \na description of the option and price where applicable\n"
    }
  ],
  "externalDocs": {
    "description": "Find out more about Scurri",
    "url": "https://www.scurri.com"
  },
  "paths": {
    "/api/2.0.0/company/{company-slug}/delivery_options/": {
      "parameters": [
        {
          "schema": {
            "type": "string"
          },
          "name": "company-slug",
          "in": "path",
          "required": true
        }
      ],
      "post": {
        "summary": "Get a list of available delivery options at checkout",
        "tags": [
          "Delivery Options"
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/DeliveryOptionsRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/DeliveryOptionsResponse"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedResponse"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundResponse"
          }
        },
        "operationId": "post-delivery-options-api-2.0.0-company-slug-delivery-options"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    },
    "schemas": {
      "AddressRequest": {
        "type": "object",
        "properties": {
          "address1": {
            "type": "string",
            "description": "the first line of the address",
            "example": "123 Fake Street"
          },
          "address2": {
            "type": "string",
            "description": "the second line of the address",
            "example": "6th Floor"
          },
          "address3": {
            "type": "string",
            "description": "the third line of the address",
            "example": "Apartment 2C"
          },
          "city": {
            "type": "string",
            "maxLength": 100,
            "description": "the city of the address",
            "example": "Dublin"
          },
          "state": {
            "type": "string",
            "maxLength": 40,
            "description": "the state of the address",
            "example": "Dublin 2"
          },
          "postcode": {
            "type": "string",
            "maxLength": 64,
            "description": "the postcode of the address",
            "example": "Y31 XP20"
          },
          "country": {
            "type": "string",
            "maxLength": 3,
            "description": "the ISO code of the country",
            "example": "IE"
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "the latitude of the address",
            "example": 0
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "the longitude of the address",
            "example": 0
          }
        }
      },
      "DestinationRequest": {
        "type": "object",
        "required": [
          "address"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "the full name for the destination address",
            "example": "John Doe"
          },
          "first_name": {
            "type": "string",
            "maxLength": 255,
            "description": "the first name for the destination address",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "maxLength": 255,
            "description": "the last name for the destination address",
            "example": "Doe"
          },
          "company_name": {
            "type": "string",
            "maxLength": 255,
            "description": "the company name for the destination address",
            "example": "The Fake Company"
          },
          "email_address": {
            "type": "string",
            "maxLength": 300,
            "description": "the email address for the destination address",
            "example": "the_fake_company@scurri.com"
          },
          "contact_number": {
            "type": "string",
            "maxLength": 40,
            "description": "the phone or mobile number for the destination address",
            "example": "021 123 4567"
          },
          "address": {
            "$ref": "#/components/schemas/AddressRequest"
          }
        }
      },
      "ItemRequest": {
        "type": "object",
        "required": [
          "weight",
          "value"
        ],
        "properties": {
          "weight": {
            "type": "number",
            "minimum": 0,
            "description": "the weight of a single item in kilograms",
            "example": 0.5
          },
          "value": {
            "type": "number",
            "minimum": 0,
            "description": "the value of a single item",
            "example": 5.99
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "the name of the item",
            "example": "Toy"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "description": "the number of items of this type within the package",
            "example": 1
          },
          "sku": {
            "type": "string",
            "maxLength": 255,
            "description": "the stock keeping unit of the item",
            "example": "SKU123"
          },
          "country_of_origin": {
            "type": "string",
            "maxLength": 3,
            "description": "the ISO code of the country",
            "example": "IE"
          },
          "harmonisation_code": {
            "type": "string",
            "maxLength": 35,
            "description": "the harmonisation code of the item",
            "example": "1234567890"
          },
          "taric_condition": {
            "type": "string",
            "maxLength": 255,
            "description": "the taric condition of the item",
            "example": "Taric123"
          },
          "vat_rate": {
            "type": "string",
            "maxLength": 16,
            "description": "the VAT rate of the item",
            "example": "23"
          },
          "import_type": {
            "type": "string",
            "maxLength": 16,
            "description": "the import type of the item",
            "example": "Gift"
          },
          "fabric_content": {
            "type": "string",
            "description": "the fabric content of the item",
            "example": "Plastic"
          }
        }
      },
      "PackageRequest": {
        "type": "object",
        "required": [
          "weight"
        ],
        "properties": {
          "width": {
            "type": "number",
            "minimum": 0,
            "description": "the width of the package in centimeters",
            "example": 12
          },
          "height": {
            "type": "number",
            "minimum": 0,
            "description": "the height of the package in centimeters",
            "example": 10
          },
          "length": {
            "type": "number",
            "minimum": 0,
            "description": "the length of the package in centimeters",
            "example": 8
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "description": "the weight of the package in kilograms",
            "example": 0.5
          },
          "description": {
            "type": "string",
            "maxLength": 255,
            "description": "the description of the items in the package",
            "example": "Toys"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemRequest"
            }
          }
        }
      },
      "InvoiceRequest": {
        "type": "object",
        "properties": {
          "incoterm": {
            "type": "string",
            "maxLength": 10,
            "description": "the incoterm rule: DAP or DDP\n",
            "example": "DAP"
          }
        }
      },
      "Enhancement": {
        "type": "object",
        "properties": {
          "Signed": {
            "type": "string",
            "description": "this is an example of a shipment enhancement",
            "example": "Yes"
          }
        }
      },
      "SettingsRequest": {
        "type": "object",
        "properties": {
          "delivery_type": {
            "type": "string",
            "description": "the setting for delivery type: ALL, HOME or LOCATION\n",
            "example": "ALL"
          }
        }
      },
      "DeliveryOptionsInvoiceResponse": {
        "type": "object",
        "properties": {
          "incoterm": {
            "type": "string",
            "maxLength": 10,
            "description": "the incoterm rule: DAP or DDP\n",
            "example": "DAP"
          }
        }
      },
      "DeliveryOptionsDeliveryPriceResponse": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "the delivery price value",
            "example": "29.99"
          },
          "currency": {
            "type": "string",
            "description": "the ISO code for the currency",
            "example": "EUR"
          }
        }
      },
      "DeliveryOptionLocationsResponse": {
        "type": "object",
        "properties": {
          "radius": {
            "type": "string",
            "description": "the radius in kilometers of the location",
            "example": "2.06"
          },
          "limit": {
            "type": "string",
            "description": "the maximum number of points returned",
            "example": "10"
          },
          "lookup_url": {
            "type": "string",
            "description": "the locations API URL",
            "example": "https://sandbox.scurri.co.uk/locations/api/company/company-slug/service-slug/"
          },
          "categories": {
            "type": "array",
            "description": "the categories included in the lookup for locations",
            "items": {
              "type": "string",
              "enum": [
                "collection_point",
                "locker",
                "store",
                "warehouse",
                "other"
              ]
            },
            "example": [
              "locker"
            ]
          }
        }
      },
      "DeliveryOptionsGroupResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the delivery option rule name",
            "example": "My Rule"
          },
          "service_id": {
            "type": "string",
            "description": "the external service identifier",
            "example": "Generic Carrier|Generic Domestic Service GDOM"
          },
          "invoice": {
            "$ref": "#/components/schemas/DeliveryOptionsInvoiceResponse"
          },
          "options": {
            "$ref": "#/components/schemas/Enhancement"
          },
          "warehouse": {
            "type": "string",
            "description": "the warehouse external identifier",
            "example": "company-slug|Warehouse Name"
          },
          "delivery_price": {
            "$ref": "#/components/schemas/DeliveryOptionsDeliveryPriceResponse"
          },
          "description": {
            "type": "string",
            "description": "the description of the delivery options rule",
            "example": "Rule for heavy items"
          },
          "locations": {
            "$ref": "#/components/schemas/DeliveryOptionLocationsResponse"
          },
          "estimated_delivery_data": {
            "type": "object",
            "properties": {
              "dates": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "a list of dates in ISO format",
                  "example": "2026-03-24"
                }
              },
              "times": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "a list of times in ISO format",
                  "example": "09:00:00"
                }
              }
            }
          }
        }
      }
    },
    "requestBodies": {
      "DeliveryOptionsRequest": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "warehouse_id",
                "recipient"
              ],
              "properties": {
                "package_type": {
                  "type": "string",
                  "maxLength": 50,
                  "description": "the package type of the shipment",
                  "example": "Parcel"
                },
                "shipping_method": {
                  "type": "string",
                  "maxLength": 350,
                  "description": "the shipment method of the shipment, mainly used to match certain rules",
                  "example": "My Mapped Rule"
                },
                "order_number": {
                  "type": "string",
                  "description": "the order number of the shipment",
                  "example": "Order-123"
                },
                "warehouse_id": {
                  "type": "string",
                  "description": "the warehouse external identifier",
                  "example": "company-slug|Warehouse Name"
                },
                "recipient": {
                  "$ref": "#/components/schemas/DestinationRequest"
                },
                "packages": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PackageRequest"
                  }
                },
                "invoice": {
                  "$ref": "#/components/schemas/InvoiceRequest"
                },
                "options": {
                  "$ref": "#/components/schemas/Enhancement"
                },
                "currency": {
                  "type": "string",
                  "maxLength": 5,
                  "description": "the ISO code for the currency",
                  "example": "EUR"
                },
                "order_value": {
                  "type": "number",
                  "minimum": 0,
                  "description": "the value of the order",
                  "example": 19.99
                },
                "rules_package_type": {
                  "type": "string",
                  "maxLength": 50,
                  "description": "the rules package type, mainly used to match certain rules",
                  "example": "My Mapped Package Type Rule"
                },
                "shipping_date": {
                  "type": "string",
                  "description": "the shipping date in ISO format, it is required to get estimated delivery data",
                  "example": "2025-07-28"
                },
                "custom_field_1": {
                  "type": "string",
                  "description": "a custom field to store anything",
                  "example": "My Custom Value 1"
                },
                "custom_field_2": {
                  "type": "string",
                  "description": "a custom field to store anything",
                  "example": "My Custom Value 2"
                },
                "custom_field_3": {
                  "type": "string",
                  "description": "a custom field to store anything",
                  "example": "My Custom Value 3"
                },
                "custom_field_4": {
                  "type": "string",
                  "description": "a custom field to store anything",
                  "example": "My Custom Value 4"
                },
                "custom_field_5": {
                  "type": "string",
                  "description": "a custom field to store anything",
                  "example": "My Custom Value 5"
                },
                "settings": {
                  "$ref": "#/components/schemas/SettingsRequest"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "DeliveryOptionsResponse": {
        "description": "the standard response when the request succeeds",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "delivery_options": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DeliveryOptionsGroupResponse"
                  }
                }
              }
            }
          }
        }
      },
      "UnauthorizedResponse": {
        "description": "standard error response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Unauthorized"
                }
              }
            }
          }
        }
      },
      "NotFoundResponse": {
        "description": "standard error response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Resource not found"
                }
              }
            }
          }
        }
      }
    }
  }
}