{ "openapi": "3.0.0", "info": { "description": "The Shipping Service Callback API enables communication between the Shipping Service and the Integrator.\n\nRead more on [Shipping assistant](https://docs.klarna.com/shipping-assistant/).", "title": "Shipping Service Callback API", "version": "1.3.0" }, "paths": { "/auth": { "post": { "requestBody": { "content": { "application/vdn.klarna.shipping.auth-v1+json": { "schema": { "$ref": "#/components/schemas/authorization_token_request" } } }, "required": true }, "responses": { "201": { "description": "Bearer token created successfully", "content": { "application/vdn.klarna.shipping.auth-v1+json": { "schema": { "$ref": "#/components/schemas/authorization_token_response" } } } }, "400": { "description": "The /auth request was malformed. In order to simplify debugging,\nthe field `failure_reason` should contain a text describing the failure reason.\n", "content": { "application/vdn.klarna.shipping.auth-v1+json": { "schema": { "$ref": "#/components/schemas/authentication_malformed_request" } } } }, "401": { "description": "Invalid or missing credentials" } }, "description": "Obtain a bearer authorization token. Aggregator specific merchant identifier and API key will be provided in the payload body, it's recommended that a merchant unique token is returned using a signed Json Web Token (JWT).\r\n\r\nThe token will be used for subsequent request for this merchant identifier using HTTP bearer authorization in the `Authorization` HTTP header with the format `Authorization: Bearer `.\r\n\r\nMore about how this works:\r\n\r\nWhen a Merchant has an agreement with the TMS, the TMS provides the Merchant with an Identifier and a Key. The Merchant then configures Kustom to use the TMS with the provided Identifier and Key. So let's say the TMS gives the Merchant these credentials: \r\n```\r\nIdentifier: \"sweMerch123\"\r\nKey: \"smOOOth\"\r\n```\r\n\r\nAs KSS prepares its authorization request to the TMS, it generates a random Nonce. KSS appends the Key to the Nonce, and then runs the Sha256 algorithm on that value to create a Digest.\r\n\r\nTo further the example, let's say KSS provided a Nonce of `'lRFUpqW7Xd'`:\r\n\r\n```\r\nNonce: \"lRFUpqW7Xd\"\r\nNonce+Key: \"lRFUpqW7XdsmOOOth\"\r\nDigest: \"8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B\"\r\n```\r\n\r\nThen KSS sends the authorization request with the Identifier, Nonce, and Digest.\r\n\r\nThe TMS authenticates the credentials by looking up their local Key for the Identifier, appending the Key to the Nonce provided by KSS, running the Sha256 algorithm on that value to create their own Digest, and then comparing that Digest to the Digest provided by KSS. If the Digests are identical, the TMS accepts the request and returns a bearer token.", "operationId": "auth", "summary": "Get an authorization token" } }, "/shippingoptions": { "post": { "parameters": [ { "description": "Authorization token on format `Bearer `", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string", "format": "string" } } ], "requestBody": { "content": { "application/vdn.klarna.shipping.get_options-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipping_options_request" } } }, "required": true }, "responses": { "200": { "description": "", "headers": { "Cache-Control": { "description": "Controls response caching, format: max-age=(seconds). Max time to cache response given the same input, the response will be re-used for up-to the given max-age. The default is no caching.\nExample: Cache-Control: max-age=60\n", "schema": { "type": "string" } } }, "content": { "application/vdn.klarna.shipping.get_options-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipping_options_response" } } } }, "400": { "description": "The /shippingoptions request was malformed.\nIn order to simplify debugging,\nthe field `failure_reason` should contain a text describing the failure reason.\n", "content": { "application/vdn.klarna.shipping.get_options-v1+json": { "schema": { "$ref": "#/components/schemas/shipping_options_malformed_request" } } } }, "401": { "description": "Invalid or expired token. A new token will be obtained." } }, "security": [ { "bearerAuth": [] } ], "description": "Gets shipping options for the given customer data, address and order lines.\r\n\r\n>It's always important to display proper expected delivery date and time, to create a smoooth customer experience. Below\r\nyou can find a table with examples of how customer will see delivery date and time that is provided in the `delivery_time`\r\nfield of shipping option. Representation can vary in case provided date points to the same date or a period, in case the\r\ndate is today, tomorrow or any date in the future. Dates in the past are ignored.\r\n\r\n| Provided values | UI presentation | Examples |\r\n| --- | --- | --- |\r\n| delivery_time.interval.earliest | Delivered after `delivery_time.interval.earliest` business days | Delivered after 3 business days |\r\n| delivery_time.interval.latest | Delivered within `delivery_time.interval.latest` business days | Delivered within 3 business days |\r\n| delivery_time.interval.earliest delivery_time.interval.latest | Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days | Delivered in 2-7 business days |\r\n| delivery_time.interval.earliest delivery_time.cutoff | Delivered after `delivery_time.interval.earliest` business days, if ordered before `delivery_time.cutoff` | Delivered after 7 business days, if ordered before 14:00 |\r\n| delivery_time.interval.latest delivery_time.cutoff | Delivered within `delivery_time.interval.latest` business days, if ordered before `delivery_time.cutoff` | Delivered within 7 business days, if ordered before 14:00 |\r\n| delivery_time.interval.earliest delivery_time.interval.latest delivery_time.cutoff | Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days, if ordered before `delivery_time.cutoff` | Delivered in 1-5 business days, if ordered before 11:30 |\r\n| delivery_time.interval.earliest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered after `delivery_time.interval.earliest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest` | Delivered after 3 business days between ca 17:00 and 18:00 |\r\n| delivery_time.interval.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered within `delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest` | Delivered within 5 business days between ca 8:00 and 17:00 |\r\n| delivery_time.interval.earliest delivery_time.interval.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest` | Delivered in 1-2 business days between ca 9:00 and 12:00 |\r\n| delivery_time.interval.earliest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered after `delivery_time.interval.earliest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff` | Delivered after 4 business days between ca. 16:00 and 18:00, if ordered before 11:30 |\r\n| delivery_time.interval.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered within `delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff` | Delivered within 3 business days between ca 10:00 and 17:00, if ordered before 11:30 |\r\n| delivery_time.interval.earliest delivery_time.interval.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff` | Delivered in 1-5 business days between ca 15:00 and 17:00, if ordered before 11:30 |\r\n| delivery_time.earliest | Delivered `delivery_time.earliest` at the earliest | Delivered tomorrow at the earliest Delivered Thursday March 5 at the earliest |\r\n| delivery_time.latest | Delivered no later than `delivery_time.latest` | Delivered today Delivered no later than tomorrow Delivered no later than Thursday, March 4 |\r\n| delivery_time.earliest delivery_time.latest | Delivered between `delivery_time.earliest` and `delivery_time.latest` | Delivered today Delivered no later than tomorrow Delivered tomorrow Delivered between Wednesday March 4 and Friday March 6 Delivered Monday April 6 Delivered between Monday April 6 and Friday May 24 |\r\n| delivery_time.earliest delivery_time.cutoff | Delivered `delivery_time.earliest` at the earliest, if ordered before `delivery_time.cutoff` | Delivered Saturday, July 25 at the earliest, if ordered before 15:00 Delivered tomorrow, if ordered before 14:00 |\r\n| delivery_time.latest delivery_time.cutoff | Delivered no later than `delivery_time.latest`, if ordered before `delivery_time.cutoff` | Delivered no later than Sunday, June 4, if ordered before 20:00 Delivered tomorrow, if ordered before 14:00 |\r\n| delivery_time.earliest delivery_time.latest delivery_time.cutoff | Delivered between `delivery_time.earliest` and `delivery_time.latest`, if ordered before `delivery_time.cutoff` | Delivered between Monday March 4 and Wednesday March 6, if ordered before 12:00 Delivered tomorrow, if ordered before 14:00 |\r\n| delivery_time.earliest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered `delivery_time.earliest` at the earliest, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest` | Delivered Saturday March 13 at the earliest, from 15:00 to 17:00 |\r\n| delivery_time.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered no later than `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest` | Delivered no later than Sunday November 9, from 9:00 to 15:00 |\r\n| delivery_time.earliest delivery_time.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered between `delivery_time.earliest` and `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest` | Delivered between Monday March 9 and Friday March 13, from 10:00 to 18:00 |\r\n| delivery_time.earliest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered `delivery_time.earliest` at the earliest, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff` | Delivered tomorrow at the earliest, from 15:00 to 18:00, if ordered before 21:00 |\r\n| delivery_time.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered no later than `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff` | Delivered no later than tmorrow, from 21:00 to 23:00, if ordered before 15:00 |\r\n| delivery_time.earliest delivery_time.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest | Delivered between `delivery_time.earliest` and `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff` | Delivered between Monday March 9 and Friday March 13, from 15:00 to 17:00, if ordered before 11:30 |", "operationId": "shippingoptions", "summary": "List shipping options" } }, "/shipment": { "post": { "parameters": [ { "description": "Authorization token on format `Bearer `", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string", "format": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/select_shipping_option_request" }, "responses": { "200": { "description": "Shipment reservation created and saved successfully", "headers": { "Location": { "description": "Full URL to this shipment. E.g. https://example.com/shipment/c2059e35-58b1-4482-ad55-5e7ef541eae4", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/vdn.klarna.shipping.select_shipment-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } }, "application/vdn.klarna.shipping.select_option-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } } } }, "201": { "description": "Shipment reservation created and saved successfully", "headers": { "Location": { "description": "Full URL to this shipment. E.g. https://example.com/shipment/c2059e35-58b1-4482-ad55-5e7ef541eae4", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/vdn.klarna.shipping.select_shipment-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } }, "application/vdn.klarna.shipping.select_option-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } } } }, "400": { "description": "The shipment reservation could not be created, for example if the recipient data is invalid or the selected shipping option is no longer available. The field `failure_reason` should be one of `shipping_option_not_available`, `cutoff_time_expired` or `shipping_address_invalid`, or if neither is applicable, a text describing the failure reason to simplify debugging.\n", "content": { "application/vdn.klarna.shipping.select_shipment-v1+json": { "schema": { "$ref": "#/components/schemas/select_shipping_option_failure_response" } }, "application/vdn.klarna.shipping.select_option-v1+json": { "schema": { "$ref": "#/components/schemas/select_shipping_option_failure_response" } } } }, "401": { "description": "Invalid or expired token. A new token will be obtained." } }, "security": [ { "bearerAuth": [] } ], "description": "This operation reserves the user selected shipping option so that the merchant is able to query and find the data and create a shipment of it.\r\n\r\nThe shipment reservation should be unique per session_id provided in the request body.\r\n\r\nThis call happens when the user clicks buy, but before the purchase has gone through. A HTTP 201 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been saved successfully.\r\n\r\nA HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See `failure_reason`.\r\n\r\nIf the purchase is successfully completed, KSS will call `POST /shipment/{id}/confirm` to confirm the reservation. See the `/confirm` call.\r\n\r\nKSS will occasionally update a created shipment. This can happen because of a failure to finalize the order or for other reasons, which will restart the shipping selection process. See the `PUT /shipment` call. If the TMS is not able to return a shipment_id in the response, identifying the reserved shipment, then KSS is forced to invoke POST on succeeding updates instead of PUT.", "operationId": "postshipment", "summary": "Select shipping option" } }, "/shipment/{shipment_id}": { "get": { "parameters": [ { "description": "Unique shipment ID.", "in": "path", "name": "shipment_id", "required": true, "schema": { "type": "string" } }, { "description": "Authorization token on format `Bearer `.", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string", "format": "string" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/vdn.klarna.shipping.get_shipment-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } } } }, "401": { "description": "Invalid or expired token. A new token will be obtained." }, "404": { "description": "No such shipment." } }, "security": [ { "bearerAuth": [] } ], "description": "Get carrier product codes for the shipment, shipment status and optional carrier tracking data.", "operationId": "getshipment", "summary": "Get shipment status" }, "put": { "parameters": [ { "description": "Unique shipment ID", "in": "path", "name": "shipment_id", "required": true, "schema": { "type": "string" } }, { "description": "Authorization token on format `Bearer `.", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string", "format": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/select_shipping_option_request" }, "responses": { "200": { "description": "Shipment reservation updated successfully.", "headers": { "Location": { "description": "Full URL to this shipment. E.g. https://example.com/shipment/c2059e35-58b1-4482-ad55-5e7ef541eae4", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/vdn.klarna.shipping.get_shipment-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } }, "application/vdn.klarna.shipping.select_option-v1+json": { "schema": { "$ref": "#/components/schemas/get_shipment" } } } }, "400": { "description": "The pre-shipment could not be updated, for example if the recipient data is invalid or the selected shipping option is no longer available. The field `failure_reason` should be one of `shipping_option_not_available`, `cutoff_time_expired` or `shipping_address_invalid`, or if neither is applicable, a text describing the failure reason to simplify debugging.\n", "content": { "application/vdn.klarna.shipping.get_shipment-v1+json": { "schema": { "$ref": "#/components/schemas/select_shipping_option_failure_response" } }, "application/vdn.klarna.shipping.select_option-v1+json": { "schema": { "$ref": "#/components/schemas/select_shipping_option_failure_response" } } } }, "401": { "description": "Invalid or expired token. A new token will be obtained." }, "404": { "description": "No such shipment (KSS will retry with a `POST /shipment` if this happens)." } }, "security": [ { "bearerAuth": [] } ], "description": "This operation updates the previously created shipment reservation (`POST -> /shipment`).\r\n\r\nThe shipment reservation should be unique per session_id provided in the request body.\r\n\r\nThis call happens when the user clicks buy, but before the purchase has gone through. This request takes place if relevant data were updated or if the user was denied a preceding purchase after /shipment call took place. The user then has the potential to change his previous selections and retry the purchase.\r\n\r\nA HTTP 200 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been updated successfully.\r\n\r\nA HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason.", "operationId": "putshipment", "summary": "Update the shipping option" } }, "/shipment/{shipment_id}/confirm": { "post": { "parameters": [ { "description": "Unique shipment ID", "in": "path", "name": "shipment_id", "required": true, "schema": { "type": "string" } }, { "description": "Authorization token on format `Bearer `.", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string", "format": "string" } } ], "responses": { "200": { "description": "Successful operation." }, "401": { "description": "Invalid or expired token. A new token will be obtained." } }, "security": [ { "bearerAuth": [] } ], "description": "This operation confirms the previously created shipment reservation (`POST -> /shipment`).\r\n\r\nAfter the last `POST /shipment` or `PUT /shipment/{id}` call, one of two things can happen:\r\n\r\n* If the purchase goes through, this endpoint is called. The call is guaranteed to happen within an hour of the last call to `POST /shipment` or `PUT /shipment/{id}`. In most cases, the call to this endpoint will come within seconds.\r\n* If the purchase does not go through, this endpoint is never called. If an hour has passed since the last call to `POST /shipment` or `PUT /shipment/{id}`, it is safe to remove the reservation of the shipment.\r\n\r\nA HTTP 401 error code will trigger an auth call. Any other HTTP response will be ignored as this is a best effort call without any possibility for consumer interaction.", "operationId": "shipmentconfirm", "summary": "Confirm shipment reservation" } } }, "x-components": {}, "servers": [ { "url": "https://api.klarna.co" } ], "components": { "requestBodies": { "select_shipping_option_request": { "content": { "application/vdn.klarna.shipping.select_option-v1+json": { "schema": { "$ref": "#/components/schemas/select_shipping_option_request" } } }, "required": true } }, "securitySchemes": { "TMSAuth": { "type": "http", "scheme": "basic" }, "bearerAuth": { "in": "header", "name": "Authorization", "type": "apiKey" } }, "schemas": { "tags": { "description": "TMS defined order or order line attributes. The tags are passed in by the merchant during order creation and passed along as is.\n\nThe TMS and Merchant use tags to direct custom business logic between themselves: (Note that these tags are examples and NOT required or related to KSS in any way)\n
    \n
  • Pricing
    • \n
      \n
    • `promo17`
      • \n
    \n
  • Option Configuration
    • \n
      \n
    • `next_day_only`
      • \n
    • `sort_by_cost_asc`
      • \n
    • `limit_8`
      • \n
    \n
  • Customer Metadata
    • \n
      \n
    • `member`
      • \n
    • `platinum`
      • \n
    \n
\n\nDifferent tags are allowed on order and order line level. For example, a merchant can provide order line detail of signifcance to the TMS, i.e. `[\"age_restricted\",\"bulky\"]`\n", "items": { "example": "member", "type": "string" }, "type": "array" }, "addon_from_tms": { "description": "Addons options allow the user to customize their shipment as desired.", "properties": { "id": { "description": "Pass-through custom ID field set by the API provider. Can be used by the API provider to match add-ons in the `POST /shipment` request with add-ons from the `POST /shippingoptions` response.", "example": "sms-pickup-point-3", "type": "string" }, "max_length": { "description": "Applies to text input add-ons. Maximum length of the text. If unset, no limit is applied.", "example": 4, "type": "integer" }, "preselected": { "default": false, "description": "If set to true, the add-on is selected by default (can be unselected by the user). Only applies to add-ons that are explicitly selectable (e.g., checkboxes and addresses, but not text inputs).", "type": "boolean" }, "price": { "default": 0, "description": "Additional cost in cents, including tax, that will be added to the option's price if the add-on is selected.", "example": 400, "type": "integer" }, "required": { "default": false, "description": "If true, the add-on is marked as mandatory and the user cannot finalize the purchase without selecting it or otherwise filling the required information.", "type": "boolean" }, "type": { "//\"description\"": "Each add-on type must appear at most once per shipping option. Type is one of:
    \n
  • sms: Displays a checkbox and an input field for a phone number, for SMS notifications on delivery status updates.
    • \n
  • email: Displays a checkbox and an input field for an email address, for email notifications on delivery status updates.
    • \n
  • floor-number: Displays an input field where the consumer can provide the exact floor they live on within a building.
    • \n
  • apartment-number: Displays an input field where the consumer can provide their exact apartment number for the courier.
    • \n
  • entry-code: Displays an input field where the consumer can provide an entry code, e.g. for the building front door.
    • \n
  • locker-code: Displays an input field where the consumer can provide a locker code, e.g. for the post box.
    • \n
  • additional-instructions: Displays an input field where the consumer can provide additional delivery information for the courier.
    • \n
  • contactless-delivery: Displays a checkbox for selecting a contactless delivery. Only available in the Nordics and Germany.
    • \n
  • leave-outside-door: Displays a checkbox to allow the package to be left by the shopper's door if they are not home when it arrives. Only available in the Nordics and Germany.
    • \n
  • evening-delivery: Displays a checkbox for selecting an evening delivery, between 1700 and 2200 on any of the delivery days.
    • \n
  • daytime-delivery: Displays a checkbox for selecting a daytime delivery, between 0800 and 1700 on any of the delivery days.
    • \n
  • expedited-packing: Displays a checkbox for selecting expedited packing. This represents a commitment from the merchant to prioritize this order within any warehouse handling or dispatchment processes.
    • \n
  • reusable-packaging: Displays a checkbox for selecting reusable packaging. This represents a commitment from the merchant to send this order using reusable packaging.
    • \n
  • sustainable-packaging: Displays a checkbox for selecting a sustainable packaging. This represents a commitment from the merchant to ensure the delivery uses easily recycleable or re-useable packaging.
    • \n
  • carbon-compensated: Displays a checkbox for the user to make a carbon offsetting donation. Contact your Kustom account manager if you would like to explore this problem space further in partnership with us.
    • \n
  • indoor-home-delivery: Displays a checkbox for selecting an indoor delivery, e.g. for large homewares or white goods.
    • \n
  • assembly-at-pickup: Displays a checkbox for selecting assembly of the goods, e.g. for sports equipment like bikes or home and garden items.
    • \n
  • package-removal: Displays a checkbox to allow the package to be removed by the merchant.
    • \n
\n", "description": "Each add-on type must appear at most once per shipping option.\n\nType is one of:\n\n- **sms**: Displays a checkbox and an input field for a phone number, for SMS notifications on delivery status updates.\n- **email**: Displays a checkbox and an input field for an email address, for email notifications on delivery status updates.\n- **floor-number**: Displays an input field where the consumer can provide the exact floor they live on within a building.\n- **apartment-number**: Displays an input field where the consumer can provide their exact apartment number for the courier.\n- **entry-code**: Displays an input field where the consumer can provide an entry code, e.g. for the building front door.\n- **locker-code**: Displays an input field where the consumer can provide a locker code, e.g. for the post box.\n- **additional-instructions**: Displays an input field where the consumer can provide additional delivery information for the courier.\n- **contactless-delivery**: Displays a checkbox for selecting a contactless delivery. Only available in the Nordics and Germany.\n- **leave-outside-door**: Displays a checkbox to allow the package to be left by the shopper's door if they are not home when it arrives. Only available in the Nordics and Germany.\n- **evening-delivery**: Displays a checkbox for selecting an evening delivery, between 17:00 and 22:00 on any of the delivery days.\n- **daytime-delivery**: Displays a checkbox for selecting a daytime delivery, between 08:00 and 17:00 on any of the delivery days.\n- **expedited-packing**: Displays a checkbox for selecting expedited packing. This represents a commitment from the merchant to prioritize this order within any warehouse handling or dispatch processes.\n- **reusable-packaging**: Displays a checkbox for selecting reusable packaging. This represents a commitment from the merchant to send this order using reusable packaging.\n- **sustainable-packaging**: Displays a checkbox for selecting sustainable packaging. This represents a commitment from the merchant to ensure the delivery uses easily recyclable or reusable packaging.\n- **carbon-compensated**: Displays a checkbox for the user to make a carbon offsetting donation. Contact your account manager if you would like to explore this area further in partnership with us.\n- **indoor-home-delivery**: Displays a checkbox for selecting an indoor delivery, e.g. for large homewares or white goods.\n- **assembly-at-pickup**: Displays a checkbox for selecting assembly of the goods, e.g. for sports equipment like bikes or home and garden items.\n- **package-removal**: Displays a checkbox to allow the package to be removed by the merchant.\n", "type": "string" }, "url": { "description": "Displays a 'Learn more' link to a web page with more information about the addon.", "example": "https://www.kustom.co", "type": "string" } }, "required": [ "type" ], "type": "object" }, "addon_user_data": { "description": "Addons options allow the user to customize their shipment as desired.", "properties": { "data": { "description": "Input from the user.", "properties": { "selected": { "//\"description\"": "User selection with the following meaning depending on add-on type:
    \n
  • sms: Indicates whether or not the user wants SMS notifications.
    • \n
  • email: Indicates whether or not the user wants email notifications.
    • \n
  • floor-number: Should be ignored.
    • \n
  • apartment-number: Should be ignored.
    • \n
  • entry-code: Should be ignored.
    • \n
  • locker-code: Should be ignored.
    • \n
  • additional-instructions: Should be ignored.
    • \n
  • contactless-delivery: Indicates whether or not the user wants a contactless delivery.
    • \n
  • leave-outside-door: Indicates whether or not the user wants the package to be left by their door if they are not home when it arrives.
    • \n
  • evening-delivery: Indicates whether or not the user wants an evening delivery.
    • \n
  • daytime-delivery: Indicates whether or not the user wants a daytime delivery.
    • \n
  • expedited-packing: Indicates whether or not the user wants expedited packing.
    • \n
  • sustainable-packaging: Indicates whether or not the user wants sustainable packing.
    • \n
  • carbon-compensated: Indicates whether or not the user wants the shipment to be carbon compensated to the extent that is priced.
    • \n
  • indoor-home-delivery: Indicates whether or not the user wants an indoor delivery.
    • \n
  • assembly-at-pickup: Indicates whether or not the user wants the goods to be assembled at the pickup location.
    • \n
  • package-removal: Indicates whether or not the user wants the package to be removed by the merchant.
    • \n
\n", "description": "User selection with the following meaning depending on add-on type:\n\n- **sms**: Indicates whether or not the user wants SMS notifications.\n- **email**: Indicates whether or not the user wants email notifications.\n- **floor-number**: Should be ignored.\n- **apartment-number**: Should be ignored.\n- **entry-code**: Should be ignored.\n- **locker-code**: Should be ignored.\n- **additional-instructions**: Should be ignored.\n- **contactless-delivery**: Indicates whether or not the user wants a contactless delivery.\n- **leave-outside-door**: Indicates whether or not the user wants the package to be left by their door if they are not home when it arrives.\n- **evening-delivery**: Indicates whether or not the user wants an evening delivery.\n- **daytime-delivery**: Indicates whether or not the user wants a daytime delivery.\n- **expedited-packing**: Indicates whether or not the user wants expedited packing.\n- **sustainable-packaging**: Indicates whether or not the user wants sustainable packaging.\n- **carbon-compensated**: Indicates whether or not the user wants the shipment to be carbon compensated to the extent that is priced.\n- **indoor-home-delivery**: Indicates whether or not the user wants an indoor delivery.\n- **assembly-at-pickup**: Indicates whether or not the user wants the goods to be assembled at the pickup location.\n- **package-removal**: Indicates whether or not the user wants the package to be removed by the merchant.\n", "type": "boolean" }, "text": { "//\"description\"": "User input with the following meaning depending on add-on type:
    \n
  • sms: Contains the phone number (non-empty if `selected` is true).
    • \n
  • email: Contains the email address (non-empty if `selected` is true).
    • \n
  • floor-number: Contains the input given by the user (can be empty).
    • \n
  • apartment-number: Contains the input given by the user (can be empty).
    • \n
  • entry-code: Contains the input given by the user (can be empty).
    • \n
  • locker-code: Contains the input given by the user (can be empty).
    • \n
  • additional-instructions: Contains the input given by the user (can be empty).
    • \n
  • contactless-delivery: Should be ignored.\n
  • leave-outside-door: Should be ignored.\n
  • evening-delivery: Should be ignored.\n
  • daytime-delivery: Should be ignored.\n
  • expedited-packing: Should be ignored.\n
  • sustainable-packaging: Should be ignored.\n
  • carbon-compensated: Should be ignored.\n
  • indoor-home-delivery: Should be ignored.\n
  • assembly-at-pickup: Should be ignored.\n
  • package-removal: Should be ignored.\n
\n", "description": "User input with the following meaning depending on add-on type:\n\n- **sms**: Contains the phone number (non-empty if `selected` is true).\n- **email**: Contains the email address (non-empty if `selected` is true).\n- **floor-number**: Contains the input given by the user (can be empty).\n- **apartment-number**: Contains the input given by the user (can be empty).\n- **entry-code**: Contains the input given by the user (can be empty).\n- **locker-code**: Contains the input given by the user (can be empty).\n- **additional-instructions**: Contains the input given by the user (can be empty).\n- **contactless-delivery**: Should be ignored.\n- **leave-outside-door**: Should be ignored.\n- **evening-delivery**: Should be ignored.\n- **daytime-delivery**: Should be ignored.\n- **expedited-packing**: Should be ignored.\n- **sustainable-packaging**: Should be ignored.\n- **carbon-compensated**: Should be ignored.\n- **indoor-home-delivery**: Should be ignored.\n- **assembly-at-pickup**: Should be ignored.\n- **package-removal**: Should be ignored.\n", "type": "string" } }, "type": "object" }, "id": { "description": "The `id` value from the `POST /shippingoptions` response.", "example": "sms-pickup-point-3", "type": "string" }, "max_length": { "description": "The `max_length` value from the `POST /shippingoptions` response.", "example": 4, "type": "integer" }, "preselected": { "description": "The `preselected` value from the `POST /shippingoptions` response.", "type": "boolean" }, "price": { "description": "The `price` value from the `POST /shippingoptions` response.", "example": 400, "type": "integer" }, "required": { "description": "The `required` value from the `POST /shippingoptions` response.", "type": "boolean" }, "type": { "description": "The `type` value from the `POST /shippingoptions` response. Type is one of:", "enum": [ "sms", "email", "floor-number", "apartment-number", "entry-code", "locker-code", "additional-instructions", "contactless-delivery", "leave-outside-door", "evening-delivery", "daytime-delivery", "expedited-packing", "sustainable-packaging", "carbon-compensated", "indoor-home-delivery", "assembly-at-pickup", "package-removal" ], "type": "string" } }, "required": [ "type", "data", "id" ], "type": "object" }, "address": { "properties": { "city": { "example": "Stockholm", "type": "string" }, "country": { "description": "2 character ISO 3166 country format", "example": "SE", "type": "string" }, "postal_code": { "description": "Normalized to country specifications", "example": "111 34", "type": "string" }, "region": { "description": "Country specific region", "example": "CA", "type": "string" }, "street_address": { "example": "Sveavägen 46", "type": "string" }, "street_address2": { "type": "string" } }, "required": [ "street_address", "postal_code", "city", "country" ], "type": "object" }, "area": { "description": "DRAFT - Geographically enclosed delivery area. WIP: Specifications might change.", "properties": { "boundary": { "description": "Polygon definition of enclosed area using decimal degree geographical coordinates", "example": [ { "lat": 18.062689527869225, "lng": 59.33655850186736 }, { "lat": 18.063891157507896, "lng": 59.336892270502865 }, { "lat": 18.06284509599209, "lng": 59.33791817815379 }, { "lat": 18.061750754714012, "lng": 59.337655548745 } ], "items": { "$ref": "#/components/schemas/coordinates" }, "type": "array" }, "price": { "description": "Price in cents including tax for this area, if different from base price. Tax rate from base price.", "example": 5000, "type": "integer" }, "type": { "description": "The type of area enclosed by the boundaries", "enum": [ "archipelago", "urban", "suburban", "rural" ], "example": "archipelago", "type": "string" } }, "required": [ "type", "boundary" ], "type": "object" }, "authentication_malformed_request": { "properties": { "failure_reason": { "example": "'example123' is not a valid user identifier", "type": "string" } } }, "authorization_token_request": { "description": "Merchant authentication data for authorizing at the TMS. The credentials consist of an identifier and an API-key, both are configured by the merchant in Kustoms systems.\nThe identifier is treated as a string and should contain enough information to identify the merchant at the TMS and any specific configuration or profile needed.\nThere should be different credentials for test/playground and production environments.\nAPI key/credentials for access to TMS is hashed using SHA-256 together with a random nonce.\n", "properties": { "identifier": { "description": "Handled as a string. Should uniquely identify the merchant at the TMS and any configuration if different profiles are available.", "example": "merchant-12345-profile-65432", "type": "string" }, "secret": { "description": "API key/credentials for to authorize the merchant", "properties": { "digest": { "description": "sha-256 digest over nonce and merchant API key. Format `sha256(nonce+key)`", "example": "8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B", "type": "string" }, "nonce": { "example": "lRFUpqW7Xd", "type": "string" } } } }, "type": "object" }, "authorization_token_response": { "properties": { "token": { "description": "Authorization token, will be used as bearer. Recommended implementation using JWT ", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudCI6ImZvb2JhciJ9.k2tE6vdJAEGbYSeZj2YluRK5vZbPAxsjd7XqARpBX3Y", "type": "string" } }, "type": "object" }, "carrier": { "description": "Transportation carrier company used.\n
    \n
  • merchant can be used for merchant self-hosted delivery methods (ex. instore pickup).
    • \n
  • generic-postal can be used to indicate a generic postal network.
    • \n
  • Additional carriers can be supported on request.
    • \n
\nValue should be one of:\n", "enum": [ "acs-courier", "airmee", "an-post", "asendia", "australia-post", "austrian-post", "bartolini", "best", "bpost", "bring", "bring-green", "budbee", "budbee-box", "budcompaniett", "bussgods", "citymail", "colis-prive", "colissimo", "collicare", "correos", "correos-express", "crown-relocations", "czech-post", "dachser", "danske-fragt", "dao", "deutsche-post", "dhl", "dhl-express", "doorier", "dooris", "dpd", "dsv", "dynalogic", "e2y", "early-bird", "emily-company", "evri", "fedex", "fietskoeriers", "generic", "generic-postal", "gls", "gordon", "helthjem", "hoekstra", "hrvatska-posta", "in-time", "instabikes", "instabox", "instabox-green", "itella", "kaukokiito", "kiitolinja", "laposte", "leen-merken", "lgt", "magyar-posta", "mat-se", "matkahuolto", "merchant", "mioo-assembly-service", "mx-transport", "mondial-relay", "mtd", "netflux", "ntex", "oda", "omniva", "onroad", "paack", "packs", "porterbuddy", "post-it", "post-luxembourg", "posta-slovenija", "posten-norge", "posti", "postnl", "postnl-extra-home", "postnord", "professional-parcel-logistic", "quick-pac", "rapido", "red-je-pakketje", "relais-colis", "royal-mail", "safe-carrier-logistics", "sagawa", "schenker", "skargarda", "slovenska-posta", "stuart", "svosj", "svosj-trial", "swiss-post", "swoopin", "trunkrs", "ups", "urbit", "urgent-cargus", "van-spreuwel", "wideroe-smart", "wolt", "yunda", "zalando" ], "example": "postnord", "type": "string" }, "coordinates": { "description": "Geographical position in decimal degrees", "properties": { "lat": { "description": "Latitude in decimal degrees", "example": 59.336946, "type": "number" }, "lng": { "description": "Longitude in decimal degrees", "example": 18.063095, "type": "number" } }, "required": [ "lat", "lng" ], "type": "object" }, "delivery_time": { "description": "Defines earliest and latest estimated delivery dates and/or times and the cutoff time for these delivery times to be met. Is used to indicate estimated delivery time to the user. Timezone should be given if time is supplied, otherwise zulu is assumed.\n\n\nNOTE: The *interval* object always overrides the explicit earliest and latest delivery dates (which means these will be ignored if an *interval* is set).", "properties": { "cutoff": { "description": "Delivery times are only valid if order is placed before this time, in ISO 8601 format.", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" }, "earliest": { "description": "Earliest possible delivery date, in ISO 8601 format.", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" }, "interval": { "description": "Defines offsets for earliest and latest estimated delivery dates, in business days. Timezone offset should be given in terms of UTC offset in seconds (see utc_offset_in_seconds), otherwise 0 is assumed.", "properties": { "earliest": { "description": "Date offset (in business days) that will be added to current local time in UTC and be presented as a delivery_time earliest date.", "example": "3", "type": "string" }, "latest": { "description": "Date offset (in business days) that will be added to current local time in UTC and be presented as a delivery_time latest date.", "example": "5", "type": "string" }, "utc_offset_in_seconds": { "description": "The UTC offset (in seconds) that will be used when formatting the evaluated date/time.", "example": "3600", "type": "string" } } }, "latest": { "description": "Parcel will be delivered at latest this date, in ISO 8601 format.", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" }, "time_of_day": { "description": "Defines earliest and latest estimated delivery times of day.", "properties": { "earliest": { "description": "Defines earliest estimated delivery time in ISO 8601 format. The date part will be ignored.", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" }, "latest": { "description": "Defines latest estimated delivery time in ISO 8601 format. The date part will be ignored.", "example": "2017-07-21T19:32:28Z", "format": "date-time", "type": "string" } } } }, "type": "object" }, "dimensions": { "description": "Dimensions of this item", "properties": { "height": { "description": "height in mm", "example": 5000, "type": "integer" }, "length": { "description": "length in mm", "example": 5000, "type": "integer" }, "width": { "description": "width in mm", "example": 5000, "type": "integer" } }, "type": "object" }, "feature": { "description": "Non-actionable feature description or piece of information. Enhances option display without allowing user input.", "properties": { "class": { "description": "Determines if the feature is an simple information box or a badge. Badges are eye-catching and colourful, highlighting a particular feature of the shipping option to draw the shopper's attention.", "enum": [ "info", "badge", "call_to_action" ], "type": "string" }, "merchant_info_text": { "description": "Text to be displayed in the info-box. Only applicable when `type` is `merchant_info_text`.", "type": "string" }, "type": { "description": "This string will determine the feature applied. Info-boxes:\n
    \n
  • distributor-will-contact: Displays an info-box to say the distributor will contact the shopper afterwards.
    • \n
  • package-removal: Displays an info-box to say the carrier will remove the packaging and dispose of it on behalf of the shopper.
    • \n
  • room-delivery: Displays an info-box to say the order will be delivered and carried into the room of the shopper's choice.
    • \n
  • delivery-time-extra-info: Displays an info-box to say the stated number of days refers to the shipping time from the merchant to the consumer.
    • \n
  • multiple-deliveries-info: Displays an info-box to say that the order will be split into multiple deliveries.
    • \n
  • merchant-info-text: Displays an info-box with the text provided in merchant_info_text
    • \n
\n Badges:\n
    \n
  • afternoon: Displays a badge highlighting that the option is an afternoon delivery option.
    • \n
  • carbon-compensated: Displays a badge highlighting that the option will be carbon compensated.
    • \n
  • eco-friendly: Displays a badge highlighting that the option is environmentally friendly.
    • \n
  • evening: Displays a badge highlighting that the option is an evening delivery option.
    • \n
  • express: Displays a badge highlighting that the option is an express option.
    • \n
  • fossil-free: Displays a badge highlighting that the shipping option is fossil free.
    • \n
  • in-door-home-delivery: Displays a badge highlighting that the shipment will be delivered indoors.
    • \n
  • morning: Displays a badge highlighting that the option is a moning delivery option.
    • \n
  • multiple-deliveries: Displays a badge highlighting that the shipment will be split into multiple deliveries.
    • \n
  • outdoor-home-delivery: Displays a badge highlighting that the shipment will be delivered outdoors.
    • \n
  • recommended: Displays a badge highlighting that the option recommended by the merchant.
    • \n
  • traceable: Displays a badge highlighting that the shipping option is traceable.
    • \n
\n Call to actions:\n
    \n
  • learn-more: Displays a 'Learn more' link to a URL with more information about the feature.
    • \n
  • size-guide: Displays a 'Size Guide' icon that links to URL with a size guide.
    • \n
\n", "type": "string" }, "url": { "description": "Displays a link to a web page with information about the feature. Only applicable when `class` is `call_to_action`.", "example": "https://www.kustom.co", "type": "string" } }, "required": [ "type" ] }, "get_shipment": { "properties": { "additional_info": { "description": "Any additional information that should be passed to a merchant from TMS can be provided here. Limit is 256 characters.", "type": "string" }, "selected_shipping_option": { "properties": { "carrier": { "$ref": "#/components/schemas/carrier" }, "carrier_product": { "properties": { "addon_identifiers": { "description": "Product addon identifiers", "items": { "example": "1", "type": "string" }, "type": "array" }, "identifier": { "description": "Carrier identifier/product code", "example": "19", "type": "string" }, "name": { "description": "Carrier product name", "example": "MyPack", "type": "string" } }, "type": "object" } }, "required": [ "carrier" ], "type": "object" }, "shipment_id": { "description": "The id of the (reserved) shipment", "example": "c2059e35-58b1-4482-ad55-5e7ef541eae4", "type": "string" }, "shipments": { "items": { "properties": { "carrier": { "$ref": "#/components/schemas/carrier" }, "tracking_id": { "description": "Carrier-specific tracking id.", "type": "string" }, "tracking_url": { "description": "Carrier-specific URL to a web page where the consumer can see and make changes to their delivery.", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "shipment_id", "selected_shipping_option" ], "type": "object" }, "get_shipping_options_request": { "properties": { "currency": { "description": "ISO 4217 alphabetic currency code.", "example": "SEK", "type": "string" }, "geoblocking": { "description": "A flag that indicates if the requested shipping options are for geoblocking flow.\n

\n Example: abc.se has consumers in e.g. Norway. According to Konsumentverket, these consumers should be given “the same opportunity to buy as a Swedish consumer”.\n

\n

\n User Flows:\n

    \n
  1. A Norwegian consumer enters abc.se
    2. \n
  2. The consumer selects Norway as billing country and fills in his/her address
    3. \n
  3. Shipping module will display an information box saying “We do not deliver to the country specified in your billing address. Please select an alternative shipping option below.”
    4. \n
  4. The consumer chooses the delivery country (only if more than one is available).\n
      \n
    1. The consumer either fills in an address and gets a full set of shipping options OR
      2. \n
    2. The consumer chooses not to fill in an address and gets presented with only pickup-merchant-store shipping options with all the Swedish stores as locations.
      3. \n
    \n
    5. \n
\n

\n", "example": true, "type": "boolean" }, "locale": { "description": "IETF BCP-47 locale definition.", "example": "sv-SE", "format": "lc-CC", "type": "string" }, "order": { "$ref": "#/components/schemas/order" }, "recipient": { "$ref": "#/components/schemas/recipient" }, "selected_shipping_option_id": { "description": "Informs what selected shipping option is currently selected by an enduser.\nWhen this information is provided it means that the API caller wants to refine\nthe locations for the selected shipping option.\nThe API endpoint should restrict its response to the selected shipping option only\nand base the refinement on the recipient data.\nThe recipient data is temporary and should not replace any state persistent (if any)\nbased on previous recipient data received in prior shippingoptions calls.\n", "example": "tms-specific-shipping-option-id", "type": "string" }, "sender": { "$ref": "#/components/schemas/sender" }, "session_id": { "description": "Unique Kustom shipping session id.", "example": "201cda14-975f-4c4d-9c2f-12f3896b5156", "type": "string" } }, "required": [ "session_id", "locale", "currency", "recipient", "order" ], "type": "object" }, "get_shipping_options_response": { "properties": { "shipping_options": { "items": { "$ref": "#/components/schemas/shipping_option" }, "type": "array" } }, "type": "object" }, "location": { "description": "A location describes a pickup location, either a pickup-point, box or store. Coordinates are optional, if not supplied KSS will attempt to use geolocation based on the address.", "properties": { "address": { "$ref": "#/components/schemas/address" }, "coordinates": { "$ref": "#/components/schemas/coordinates" }, "delivery_time": { "$ref": "#/components/schemas/delivery_time" }, "id": { "description": "Optional TMS provided identifier, will be passed back if provided.", "example": "loc-12345", "type": "string" }, "name": { "description": "User friendly name of location (pickup point, store name, etc).", "example": "ICA supermarket", "type": "string" }, "operational_hours": { "$ref": "#/components/schemas/operational_hours" }, "price": { "description": "Price in cents including tax for this location, if different from base price. Tax rate from base price.", "example": 0, "type": "integer" } }, "required": [ "name", "address" ], "type": "object" }, "open_hours": { "description": "Opening and closing times for (part of) a given day (24 hs Format. e.g. '09:00', '18:00'). Assumes local timezone.", "properties": { "always_open": { "default": false, "description": "Open all day", "type": "boolean" }, "close": { "description": "24 hs Format (e.g. 18:00)", "example": "22:00", "type": "string" }, "closed": { "default": false, "description": "Closed all day", "type": "boolean" }, "open": { "description": "24 hs Format (e.g. 09:00)", "example": "09:00", "type": "string" } }, "type": "object" }, "operational_hours": { "description": "Opening and closing times for a location (24 hs Format. e.g. '09:00', '18:00'). If operational hours are unknown, do not provide this object. Otherwise, provide hours or an open/closed status for each day, either using default hours or providing overrides for each day of the week.", "properties": { "default": { "description": "Opening and closing hours (24 hs Format. e.g. '09:00', '18:00') *OR* an open/closed status for each day of the week", "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "overrides": { "properties": { "date": { "items": { "properties": { "date": { "example": "2017-12-24", "format": "date", "type": "string" }, "hours": { "$ref": "#/components/schemas/open_hours" } }, "type": "object" }, "type": "array" }, "weekday": { "properties": { "fri": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "mon": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "sat": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "sun": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "thu": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "tue": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" }, "wed": { "items": { "$ref": "#/components/schemas/open_hours" }, "type": "array" } } } } } }, "type": "object" }, "order": { "description": "Order definition", "properties": { "tags": { "$ref": "#/components/schemas/tags" }, "id": { "description": "Kustom order id, will be known at time of purchase and only provided in the `/shipment` call. No assumption should be made about the format.", "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/order_lines" }, "type": "array" }, "total_amount": { "description": "Total order amount including tax in cents.", "example": 10000, "type": "integer" }, "total_tax": { "description": "Total tax of the order amount in cents.", "example": 2500, "type": "integer" }, "total_weight": { "description": "Total weight in grams", "example": 2000, "type": "integer" } }, "required": [ "total_amount", "total_tax", "lines" ], "type": "object" }, "order_line_attributes": { "properties": { "tags": { "$ref": "#/components/schemas/tags" }, "dimensions": { "$ref": "#/components/schemas/dimensions" }, "weight": { "description": "Weight of this item in grams", "example": 1000, "type": "integer" } }, "type": "object" }, "order_lines": { "description": "Rich order line information", "properties": { "attributes": { "$ref": "#/components/schemas/order_line_attributes" }, "quantity": { "example": 2, "type": "integer" }, "reference": { "description": "Merchant provided item reference", "example": "sku-1234", "type": "string" }, "tax_rate": { "description": "Tax rate of shipping option in percent. Non-negative, two implicit decimals. I.e 2500 = 25.00%.", "example": 2500, "type": "integer" }, "total_discount_amount": { "description": "Total discount amount in cents", "example": 1000, "type": "integer" }, "total_price_including_tax": { "description": "Total price of items, including tax, given in cents", "example": 4000, "type": "integer" }, "total_tax_amount": { "description": "Total tax amount in cents", "example": 1250, "type": "integer" }, "type": { "description": "Order line type.", "enum": [ "physical", "discount", "shipping_fee", "sales_tax", "digital", "gift_card", "store_credit", "surcharge" ], "type": "string" }, "unit_price": { "description": "Unit price in cents", "example": 2500, "type": "integer" } }, "required": [ "quantity", "unit_price", "tax_rate", "total_tax_amount", "total_price_including_tax" ], "type": "object" }, "recipient": { "description": "Information about the recipient", "properties": { "care_of": { "type": "string" }, "city": { "example": "Stockholm", "type": "string" }, "company_name": { "description": "Applicable only if recipient is a company", "example": "Kustom AB", "type": "string" }, "country": { "description": "2 character ISO 3166 country format", "example": "SE", "type": "string" }, "customer_type": { "description": "B2C or B2B customer type. Note: does only indicate the type of customer, not if the address is residential or business.", "enum": [ "person", "organization" ], "type": "string" }, "email": { "example": "info@kustom.com", "type": "string" }, "family_name": { "example": "Joyce", "type": "string" }, "given_name": { "example": "Klara", "type": "string" }, "phone": { "description": "E.164 international format", "example": "+46812012010", "type": "string" }, "postal_code": { "description": "Normalized to country specifications", "example": "111 34", "type": "string" }, "region": { "description": "Country specific region", "example": "CA", "type": "string" }, "street_address": { "example": "Sveavägen 46", "type": "string" }, "street_address2": { "type": "string" } }, "required": [ "country" ], "type": "object" }, "select_shipping_option_failure_response": { "description": "Reason the shipment reservation couldn't be created", "properties": { "failure_reason": { "example": "shipping_option_not_available", "type": "string" } }, "type": "object" }, "select_shipping_option_request": { "properties": { "currency": { "description": "ISO 4217 alphabetic currency code", "example": "SEK", "type": "string" }, "locale": { "description": "IETF BCP-47 locale definition", "example": "sv-SE", "format": "lc-CC", "type": "string" }, "order": { "$ref": "#/components/schemas/order" }, "recipient": { "allOf": [ { "$ref": "#/components/schemas/recipient" }, { "required": [ "given_name", "family_name", "street_address", "postal_code", "city" ] } ] }, "selected_shipping_option": { "properties": { "addons": { "items": { "$ref": "#/components/schemas/addon_user_data" }, "type": "array" }, "carrier": { "description": "The carrier for this option", "example": "dhl", "type": "string" }, "class": { "description": "The shipping class for this option", "example": "express", "type": "string" }, "id": { "description": "Optional TMS provided identifier", "example": "option-1234", "type": "string" }, "location": { "properties": { "address": { "$ref": "#/components/schemas/address" }, "coordinates": { "$ref": "#/components/schemas/coordinates" }, "id": { "description": "Optional TMS provided identifier", "example": "location-1234", "type": "string" }, "name": { "description": "Name of location", "example": "ICA Supermarket", "type": "string" } }, "type": "object" }, "price": { "description": "Total price for this option in cents, including extras and tax", "example": 2500, "type": "integer" }, "tax_rate": { "description": "Tax rate of shipping option.", "example": 2500, "type": "integer" }, "timeslot": { "properties": { "end": { "description": "End of timeslot in ISO 8601 format", "format": "date-time", "type": "string" }, "id": { "description": "Optional TMS provided identifier", "example": "timeslot-1234", "type": "string" }, "start": { "description": "Start of timeslot in ISO 8601 format", "format": "date-time", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": { "description": "The type of shipping option", "example": "delivery-address", "type": "string" } }, "required": [ "id" ], "type": "object" }, "sender": { "$ref": "#/components/schemas/sender" }, "session_id": { "description": "Unique Kustom shipping session id.", "example": "201cda14-975f-4c4d-9c2f-12f3896b5156", "type": "string" } }, "required": [ "session_id", "locale", "currency", "recipient", "selected_shipping_option" ], "type": "object" }, "sender": { "description": "Information about the sender. Should indicate from where the goods are dispatched. This object is optional and can be empty.", "properties": { "address": { "$ref": "#/components/schemas/address" }, "sender_id": { "description": "Optional merchant provided sender identifier. Can be used to identify different warehouses within the same country or different dispatch routes that can affect delivery time.", "example": "warehouse-13", "type": "string" } }, "type": "object" }, "shipping_option": { "properties": { "addons": { "items": { "$ref": "#/components/schemas/addon_from_tms" }, "type": "array" }, "area": { "$ref": "#/components/schemas/area" }, "carrier": { "$ref": "#/components/schemas/carrier" }, "class": { "default": "standard", "description": "Description:\n
    \n
  • standard: Normal delivery time.
    • \n
  • economy: Slow delivery.
    • \n
  • express: Fast delivery.
    • \n
  • courier: Fastest delivery time, like food delivery.
    • \n
\nValue should be one of:\n", "enum": [ "standard", "economy", "express", "courier" ], "type": "string" }, "delivery_time": { "$ref": "#/components/schemas/delivery_time" }, "features": { "items": { "$ref": "#/components/schemas/feature" }, "type": "array" }, "free_above": { "description": "The total amount threshold at which the shipping option price becomes free, i.e. 0.00. In cents, i.e. 10000 = 100.00.", "example": 10000, "type": "integer" }, "id": { "description": "Aggregator provided identifier. Must be unique.", "example": "option-1234", "type": "string" }, "locations": { "description": "Location definitions of pickup points/boxes, store locations, etc.", "items": { "$ref": "#/components/schemas/location" }, "type": "array" }, "name": { "description": "Carrier product name. Will only be used as a fallback in case Kustom does not have a proper copy string for the shipping option.", "example": "FedEx Priority", "type": "string" }, "preview": { "description": "Should be set to true if this option was included as a result of partial address data and that it might be changed or removed when full address data is available.", "example": false, "type": "boolean" }, "price": { "description": "Price of shipping option in cents including tax. I.e. 4000 = 40.00.", "example": 4000, "type": "integer" }, "tax_rate": { "description": "Tax rate of shipping option in percent. Non-negative, two implicit decimals. I.e 2500 = 25.00%. The amount of tax will be calculated as price - (price * 10000 / (10000 + tax_rate)).", "example": 2500, "type": "integer" }, "timeslots": { "description": "Timeslot definition, only applicable to delivery methods with timeslots.", "items": { "$ref": "#/components/schemas/timeslot" }, "type": "array" }, "type": { "description": "
    \n
  • boat-delivery: Delivery by boat.
    • \n
  • click-collect: Order goods online for reservation and pick up at a merchant store.
    • \n
  • delivery-address: To address/door delivery, final selected option will contain an address and potential timeslot.
    • \n
  • generic-pickup: Delivery to a pickup point when location is unknown.
    • \n
  • generic-shipping: Shipping option when the carrier decides shipping method.
    • \n
  • office-delivery: Delivery to an office address. For eg. to an office reception.
    • \n
  • pallet-delivery: Home delivery of big/heavy goods by truck and on a pallet.
    • \n
  • crane-delivery: Delivery by crane for very large goods, such as pools and jacuzzis.
    • \n
  • pickup-box: Delivery to a pickup locker/box. Final selected option will contain a location.
    • \n
  • pickup-merchant-store: Delivery to a merchant store for pickup. Final selected option will contain a location.
    • \n
  • pickup-point: Delivery to a pickup point. Final selected option will contain a location.
    • \n
  • pickup-warehouse: Delivery to a merchant warehouse for pick up.
    • \n
  • postal: Best-effort delivery of a package/letter using the postal network.
    • \n
\n", "example": "pickup-point", "type": "string" } }, "required": [ "id", "type", "carrier", "price", "tax_rate" ], "type": "object" }, "shipping_options_malformed_request": { "properties": { "failure_reason": { "example": "Field 'xxx.yyy.example' must not be empty.", "type": "string" } } }, "timeslot": { "description": "Delivery timeslot definition. A timeslot is a range of time at which a parcel will be delivered, it can be day slots and/or time slots with minute precision. Timeslots can be overlapping.", "properties": { "cutoff": { "description": "Timeslot only valid if order is placed before this time", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" }, "end": { "description": "End time of slot in ISO 8601 format", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" }, "id": { "description": "Optional TMS provided identifier, will be passed back if provided", "example": "slot-12345", "type": "string" }, "price": { "description": "Price in cents including tax for this slot, if different from base price. Tax rate from base price.", "example": 0, "type": "integer" }, "start": { "description": "Start time of slot in ISO 8601 format", "example": "2017-07-21T17:32:28Z", "format": "date-time", "type": "string" } }, "required": [ "start", "end" ], "type": "object" } } } }