Checkout Production

## Sections
• [Getting Started](https://app.theneo.io/nshiftone/checkout/nshift-checkout-options-api.md): Welcome to nShift Checkout! nShift Checkout integrates flexible delivery options into your ecommerce experience to lift conversion, reduce friction, and streamline fulfillment. Give consumers the delivery options they want and watch cart abandonment drop. This is technical documentation intended for developers. For user guides on configuring the product, adding shipping options, adjusting prices, and related topics, please refer to our Help Center . An active nShift Checkout agreement is required to access the functionality described in this documentation. The availability of features depends on your subscription plan. If you do not have an nShift Checkout agreement and would like to learn more, please request a demo or contact your sales representative.
  • [Documentation Overview](https://app.theneo.io/nshiftone/checkout/nshift-checkout-options-api/features.md): This section provides a high-level overview of the Checkout API documentation, with links to key sections and brief explanations of their purpose. Basic Flow : a n overview of the basic integration flow, outlining the key steps to follow when working with the nShift Checkout API. Authentication : describes how to create the Client ID and Client Secret , which are required to generate an access token . Delivery Options : describes how to create a session and fetch delivery options within that session. Partial Shipments : describes all endpoints related to partial shipments. Creating a partial shipment is mandatory, while the use of the other endpoints is optional. Split Shipment : describes the split shipment endpoints. Own Pickup Locations API : documentation on how to manage own pickup locations via API. Widget : documentation on the Checkout widget. Senders : describes all Senders endpoints that can be used to create, update, and manage Senders via the API Configurations : describes all Configuration endpoints that can be used to create, update, and manage configurations via the API. Connections : describes all Connection endpoints that can be used to create, update, and manage Connections via the API.
  • [Glossary](https://app.theneo.io/nshiftone/checkout/nshift-checkout-options-api/terminology.md): This section explains key terms and concepts used throughout the Checkout documentation. nShift Portal The nShift administration portal where merchants configure Checkout, manage delivery options and rules, and administer API credentials (client ID and client secret). The Portal is used for setup and ongoing configuration, not for runtime checkout interactions. https://www.nshiftportal.com/checkout Shipping Solution The system used to book shipments and generate shipping labels after an order has been placed. Checkout determines the available delivery options, while the shipping solution handles fulfillment and carrier booking. nShift shipping solutions (sometimes also refferred to as “book & print platforms"): Delivery, Ship and Transsmart. Configuration A configuration allows merchants to control and tailor the Checkout experience, such as selecting which carrier services are offered, setting delivery prices, and enabling or disabling Checkout features. Group A collection of configurations that can be used within a Connection. Groups enable flexible routing by allowing Checkout to select a configuration from the group based on defined rules or conditions, rather than pointing to a single fixed configuration. Connection The link between Checkout and a specific Configuration or Group. A connection determines which configuration, group, or experiment, is used when Checkout is loaded, allowing the same integration to apply different Checkout setups depending on site, market, or use case. Connection ID A unique identifier used to reference a specific connection in Checkout. The Connection ID is found in the user interface once logged in to nShift Checkout, Delivery Option The representation of a selectable delivery alternative in nShift Checkout. A delivery option is what the end consumer sees and chooses during checkout. Each delivery option is based on a carrier service and include attributes such as for example price, delivery time, pickup points, or timeslots. Service (Carrier Service) A carrier-defined shipping service (for example home delivery, pickup, or express) that describes how a shipment is delivered. Services are provided by carriers and are the building blocks used to create delivery options in Checkout. PUDO (Pick Up Drop Off) A delivery method where shipments are delivered to, and collected from, a designated pickup location instead of a home address. In Checkout, PUDO typically refers to carrier pickup points, lockers, or merchant-owned pickup locations where the consumer selects a location during checkout. URI Parameter A resource identifier defined in the path segment of the request i.e. <domain-segment>/v1/shipping-options/ 4cxx3bf4-56xx-44a4-xxxx-669b48a8xx0 Query Parameter A variable passed in a request using the query segment i.e. <path-segment>? sort=asc. Body Parameter A field in the JSON request payload i.e. { “id”: "4cxxxbf4-5xx7-44a4-xxxx-669b48a8dxx0" }
  • [Data Types and Formats](https://app.theneo.io/nshiftone/checkout/nshift-checkout-options-api/data-types.md): If not specified in the different services, refer to this table Title Name Type Format Date String YYYY-MM-DD Country Code String Standard ISO-3166-1 alpha-2 Currency Code String Standard ISO-4217 Locale ID String Refer to the Language Tag column in this documentation https://www.oracle.com/java/technologies/javase/jdk21-suported-locales.html
• [Basic Flow](https://app.theneo.io/nshiftone/checkout/shipping-options-sessions-resource.md): Below is an overview of the basic integration flow, outlining the key steps to follow when working with the nShift Checkout API. 1 Get your Client ID and Secret Generate a Client ID and Client Secret in the nShift Portal, or ask your administrator to provide you with a set. These credentials are required for authentication. Follow this guide 2 Issue an Access Token Use your Client ID and Client Secret to issue an access token. This token is required to create a session and access all nShift Checkout features. Tokens are valid for 1 hour . After expiration, you must re-authenticate to obtain a new one. Follow this guide 3 Create a Session Use your access token and a Connection ID to create a session. A session is required to access nShift Checkout features. Follow this guide 4 Fetch Delivery Options Once a session is created, you can fetch available delivery options. Ensure that you include all required body parameters, including any parameters used within a configuration's rule engine. Follow this guide 5 Create a Partial Shipment After the consumer selects a delivery option and completes the purchase, create a partial shipment. Note: Creating a partial shipment is mandatory , and it ensures full compatibility with all existing and future nShift Checkout features. Follow this guide If you need to implement split shipment logic, please refer to our dedicated Split Shipment endpoints for full details.
• [Authentication](https://app.theneo.io/nshiftone/checkout/authentication.md): This section describes how to create the Client ID and Client Secret , which are required to generate an access token .
  • [Create Client ID and Secret](https://app.theneo.io/nshiftone/checkout/authentication/create-clientid-and-secret.md): A Client ID and Client Secret are required to authenticate and generate tokens, which are then used to create a session and access all nShift Checkout features. To create a Client ID and Client Secret, follow these steps: 1 Go to nShift Portal Log into nShift Portal with your user account. Note : you need to be an ‘ Owner ’ or ‘ Admin’ ' to have the permission to generate Client IDs and Secrets. 2 Go to Settings Click on Settings in the top right corner. 3 Go to Clients API Settings Choose API Configuration > Clients in the left side menu. 4 Create a new Client ID/Secret On the Clients page, click the Add button. 5 Fill-in details Fill in Display name and Description . Choose a name and a description that will make it easier to identify the token later on. Check the Enable box to enable the token right away. You may enable or disable the token at any time after it has been created. Choose Public checkout API under Allowed Scopes which are the APIs you need access to. 6 Click Save Your Client ID and Client Secret will now be generated and displayed on the screen. Important: The Client Secret will not be available after you close the popup so make sure to copy it. 7 Click Close The Client ID will now be listed on the Clients page. You can click on a Client ID at any time to edit or delete it or to enable/disable it.
  • [Issue Token](https://app.theneo.io/nshiftone/checkout/authentication/issue-a-token.md): Use your Client ID and Client Secret to generate an access token. To do this, make a POST request to the following endpoint: https://account.nshiftportal.com/idp/connect/token A token is valid for 1 hour . A recommended approach is to implement exponential backoff handling. If a request to issue token fails, retry the request with progressively longer intervals. Plain text POST https://account.nshiftportal.com/idp/connect/token Cache-Control: no-cache Content-Type: application/x-www-form-urlencodedclient_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials If the request is valid and the client is configured correctly, a JSON response is returned: JSON { "access_token": "some-real-token-data-dskjfhsuijkdhfgjkasjdgfhqoeiefoiknsoidfgvoiltgjvpdrofjmwpkldujrftvoifgkhbnilsakjprotglijkqp2owrlfjkvmowrifgho2qw9ouejifpe9rodtuj3-0porfij9odtujgw0etioyh", "expires_in": 3600, "token_type": "Bearer" }
• [Delivery Options](https://app.theneo.io/nshiftone/checkout/delivery-options.md): This section describes how to create a session and fetch delivery options within that session. If you need to implement split shipment logic, please refer to our dedicated Split Shipment endpoints for full details.
  • [Create Session](https://app.theneo.io/nshiftone/checkout/delivery-options/create-session.md): To create a session your need a bearer token and the Connection ID you want to use as a URI parameter. The Connection ID is static, in the Checkout UI you can easily change what the Connection ID points to (configuration, group, or experiment) without updating your code. For more information, see the article on managing connections in our Help Center . To find your Connection ID , log in to nShift Checkout , navigate to Connections in the top menu, and locate your Connection ID in the list. The values in the body are not mandatory but sending a body is required (empty if needed). Body values should be used if the Connection is pointing to a Group and/or an Experiment using Conditions. The Body Parameters will be used to evaluate Conditions and use the correct Configuration. The create session call creates a session that is valid for 4 hours. Each interaction with the session refreshes its validity period to 4 hours from the time of that interaction. Example: If a session is created at 13:05, it will initially be valid until 17:05. If an interaction occurs at 13:44, the validity is extended to 17:44.
  • [Fetch Delivery Options](https://app.theneo.io/nshiftone/checkout/delivery-options/fetch-delivery-options.md): To fetch Delivery Options use your session . Sending the Session ID as a URI parameter and a Body is required. The session bears in itself which configuration will be used. The values sent in the Body are used to retrieve the relevant delivery option filtered by our internal engine and your condition rules (if any). Conditions rules are set-up in the UI in the checkout configuration or programatically using the Configurations endpoint .
• [Partial Shipments](https://app.theneo.io/nshiftone/checkout/shipments.md): This section describes all endpoints related to partial shipments. Creating a partial shipment is mandatory , while the use of the other endpoints is optional.
  • [Create Partial Shipment](https://app.theneo.io/nshiftone/checkout/shipments/create-shipment.md): Once an order in the webshop has converted, create a partial shipment. You can then use this data to create the actual shipment in your shipping solution. nShift shipping solutions (sometimes also refferred to as “book & print platforms"): Delivery, Ship and Transsmart. Note: Creating a partial shipment is mandatory , and it ensures full compatibility with all existing and future nShift Checkout features. In the Sender used in your checkout configuration, add the API credentials for your shipping solution account. When you use this endpoint to create a partial shipment, it will be created in the linked shipping solution account and will also appear in the Shipment log in the nShift Checkout UI. Please note: Creating the actual shipment (complete booking and printing labels) from the partial shipment requires further actions within your shipping solution. For historical reasons the term partial shipment might not be consistent across the different shipping solutions, cf Prepared Shipment in Delivery/Transsmart and Store Order in Ship. Delivery: Link to nShift Help Center article on "Prepared Shipments" Ship: Link to nShift Help Center article on "Using StoreOrder to Save Orders for Import" Transsmart: Link to nShift Help Center article on "Prepared Shipments"
  • [Delete Partial Shipment](https://app.theneo.io/nshiftone/checkout/shipments/delete-shipment.md): To delete a shipment stored in nShift Checkout. Note: It is not possible to delete a shipment in your Book&Print platform using this method.
  • [Fetch Partial Shipment](https://app.theneo.io/nshiftone/checkout/shipments/fetch-shipment.md): Fetch a shipment information stored in NShift Checkout.
  • [Fetch Partial Shipments](https://app.theneo.io/nshiftone/checkout/shipments/fetch-shipments.md): Fetch all your shipments stored in NShift Checkout. You can filter the list by passing in parameters.
  • [Anonymize Partial Shipment by Id](https://app.theneo.io/nshiftone/checkout/shipments/anonymize-shipment-by-id.md)
  • [Anonymize Partial Shipment by Name or Email](https://app.theneo.io/nshiftone/checkout/shipments/anonymize-shipment-by-sender.md)
• [Split Shipment](https://app.theneo.io/nshiftone/checkout/split-shipment.md): Split shipment support in nShift Checkout is enabled exclusively through the dedicated split shipment API endpoints described in this section. There are no configuration flags or UI settings that turn this feature on or off. Because of this, any checkout configuration, connection, group, or experiment can be used for split shipment scenarios, as long as the integration uses the correct endpoints. Merchants that support both split shipment and non-split shipment scenarios can rely exclusively on the split shipment endpoints. The split shipment API fully supports single shipment, however, the opposite is not supported: Split shipment endpoints → can handle both single and multiple sub-shipments. Regular single-shipment endpoints → cannot be used for split shipment scenarios. For this reason, integrators who anticipate using split shipments at any point are recommended to implement only the split shipment endpoints to cover all use cases with one unified flow. Integration Flow - Split Shipment Endpoints From an integration perspective, the split shipment flow follows the same overall pattern as a standard single-shipment Checkout integration, but uses dedicated split shipment endpoints to manage multiple shipments within a single order. The key difference is that you work with multiple sub-shipments instead of one shipment. At a high level, the flow looks like this: 1 Issue an Access Token Follow this guide. 2 Create a Session POST /options/v1/split-shipments/sessions/{checkoutConnectionId} Use your access token and a Connection ID to create a session using the split shipment session creation endpoint and include the list of subShipments. If needed the Session can be updated, via PUT /split-shipments/sessions/{sessionId} , for example if there is a need to add or remove subShipments based on changes in the cart. 3 Fetch Delivery Options POST /options/v1/split-shipments/shipping-options/{sessionId} Retrieve available delivery options for each sub-shipment. Each sub-shipment may return different options depending on rules, carriers, or configuration. 4 Create Partial Shipments POST /shipments/v1/split-shipments/shipments Once the consumer has selected delivery options for each sub-shipment, create the corresponding partial shipments. subShipment Objects The split shipment endpoints accept a list of subShipment objects, each representing one shipment that together form a single checkout session. It is the webshop integration’s responsibility to determine how the items in the cart should be divided into sub-shipments. Sub-shipments should only be created when different shipping options are expected or required between parts of the same order. Warehouse packaging logic does not determine whether split shipment is needed. For example: A carrier may only allow one physical package per shipment. A customer ordering three large items may therefore result in three physical shipments handled by the carrier. However, if all items can be shipped using the same shipping option, then the checkout should not use split shipment.
  • [Create Session: Split Shipment](https://app.theneo.io/nshiftone/checkout/split-shipment/new-section.md): Just as for a single shipment checkout the first step is to create a session. But unlike the single shipment variant there are some mandatory information in the request body when creating a split shipment session. It is the webshop integration’s responsibility to determine how the items in the cart should be divided into subShipments . The main mandatory information that must be included in the body is the subShipments array. Each object in this array will represent one shipment. The customer will need to make a separate selection of a shipping option for each shipment before the checkout is complete. In the absolute simplest case the subShipments array can contain an empty object for each shipment. So to create a session for a checkout that will need three shipments this would be the simplest possible body: Plain text { "subShipments": [{}, {}, {}] } Replacing the Sender’s Address Information If needed the sender’s address information can be replaced by using the mainSenderOverride and/or sendersOverride properties. The address information of the sender selected on the top level of a checkout configuration will be replaced completely by the properties of the object in mainSenderOverride . To replace the address information of a sender selected on one or more of the shipping options, use the UUID of the sender selected on the option. Add the UUID as a key in sendersOverride and have the value be an object with the address information. Note that only the address information is replaced. Any selected Shipping Solution information or carrier specific credentials will remain unchanged on the sender. Response The two most important properties in the response are sessionId and subShipmentId . For the first shipment the subShipmentId will be equal to the sessionId. Any shipments after that will have their own unique subShipmentId.
  • [Update Session: Split Shipment](https://app.theneo.io/nshiftone/checkout/split-shipment/update-session-split-shipment.md): To change the number of shipments that are needed in a session use: PUT /options/v1/split-shipments/sessions/{sessionId} The request body is the same as when creating a session but subShipmentId can be sent in with each object in the subShipments array to preserve existing shipments. This endpoint should be used if a consumer changes the shopping cart in a way the would change the number of shipments. It can also be used if a group or experiment is used that has conditions that depends on parameters affected by user inputs.
  • [Fetch Delivery Options: Split Shipment](https://app.theneo.io/nshiftone/checkout/split-shipment/fetch-delivery-options-split-shipment.md): To request shipping options for a split shipment session use: POST /options/v1/split-shipments/shipping-options/{sessionId} NOTE: The subShipmentId property of each shipment must be set from the ones found in the response when a session was created. This ensures that each shipment is handled consistently. All of the properties available on a single shipment request for shipping options are available on this endpoint too. The difference is that they might be extracted from each shipment if the properties are always the same for all shipments. This includes properties such as receiver, language and currency. Also note that mainSenderOverride and senderOverrides are available in this endpoint to make it possible to change the sender address information before fetching valid delivery options. Response In the response each shipment object inside the subShipments array will have all the information about shipping options as if it were a single shipment. A few properties found in a single shipment response are placed on top response object, such as language and sessionId . A split shipment response from this endpoint can be used in the nShift Checkout widget. It will automatically adjust the presentation to allow a user to select a shipping option for each shipment.
  • [Create Partial Shipments: Split Shipment](https://app.theneo.io/nshiftone/checkout/split-shipment/fetch-delivery-options-split-shipment-1.md): When the consumer has completed the checkout process all of the shipments in a split shipment session can be created with a call to: POST /shipments/v1/split-shipments/shipments The subShipments array holds the customer selected data for each partial shipment. Most of the information needed for each shipment is available from the fetched delivery o ptions or from the result of the nShift Checkout widget.
• [Own Pickup Locations API](https://app.theneo.io/nshiftone/checkout/own-pickup-locations-api.md): If you want to offer own pickup locations in Checkout, such as stores, warehouses, or other merchant-managed locations used for Click & Collect, the pickup locations can either be maintained via the user interface in nShift Portal or by using our dedicated Own Pickup Locations API. Full details of the Own Pickup Locations API can be found here .
• [Widget](https://app.theneo.io/nshiftone/checkout/widget.md): The nShift Checkout Widget offers a convenient way to display shipping options directly in webshops, without requiring ongoing updates when new delivery features are introduced. Using the widget is completely optional - merchants can also choose a fully headless integration if they prefer full control. The widget can be styled and customized using CSS to match your site’s design. All widget configuration and implementation instructions are documented in our Help Center. Click here to view the widget documentation.
• [Senders](https://app.theneo.io/nshiftone/checkout/senders.md): This section describes all Senders endpoints that can be used to create, update, and manage Senders via the API. Note: Senders can also be managed through the nShift Checkout UI. Use of these endpoints is optional.
  • [Create Sender](https://app.theneo.io/nshiftone/checkout/senders/create-sender.md)
  • [Update Sender](https://app.theneo.io/nshiftone/checkout/senders/update-sender.md)
  • [Delete Sender](https://app.theneo.io/nshiftone/checkout/senders/delete-sender.md)
  • [Fetch Sender](https://app.theneo.io/nshiftone/checkout/senders/fetch-sender.md)
  • [Fetch Senders](https://app.theneo.io/nshiftone/checkout/senders/fetch-senders.md)
• [Configurations](https://app.theneo.io/nshiftone/checkout/configurations.md): This section describes all Configuration endpoints that can be used to create, update, and manage configurations via the API. Note: Configurations can also be managed through the nShift Checkout UI. Use of these endpoints is optional.
  • [Create Configuration](https://app.theneo.io/nshiftone/checkout/configurations/create-configuration.md)
  • [Update Configuration](https://app.theneo.io/nshiftone/checkout/configurations/update-configuration.md)
  • [Delete Configuration](https://app.theneo.io/nshiftone/checkout/configurations/delete-configuration.md)
  • [Fetch Configuration](https://app.theneo.io/nshiftone/checkout/configurations/fetch-configuration.md)
  • [Fetch Configurations](https://app.theneo.io/nshiftone/checkout/configurations/fetch-configurations.md)
  • [Fetch Configuration Status](https://app.theneo.io/nshiftone/checkout/configurations/fetch-configuration-status.md)
  • [Update Configuration Status](https://app.theneo.io/nshiftone/checkout/configurations/update-configuration-status.md)
  • [Fetch Configuration Versions](https://app.theneo.io/nshiftone/checkout/configurations/fetch-configuration-versions.md)
• [Connections](https://app.theneo.io/nshiftone/checkout/connections.md): This section describes all Connection endpoints that can be used to create, update, and manage Connections via the API. Connections are used as a reference towards a Configuration or a Group (and/or an Experiment) to be used. This allows users to change the set-up without having to modify their integration towards nShift Checkout. Note: Connections can also be managed through the nShift Checkout UI. Use of these endpoints is optional.
  • [Create Connection](https://app.theneo.io/nshiftone/checkout/connections/create-connection.md)
  • [Update Connection](https://app.theneo.io/nshiftone/checkout/connections/update-connection.md)
  • [Delete Connection](https://app.theneo.io/nshiftone/checkout/connections/delete-connection.md)
  • [Fetch Connection](https://app.theneo.io/nshiftone/checkout/connections/fetch-connection.md)
  • [Fetch Connections](https://app.theneo.io/nshiftone/checkout/connections/fetch-connections.md)
• [Metrics](https://app.theneo.io/nshiftone/checkout/metrics.md): Get usage data between two dates. The dates are inclusive so setting the same start and end date will get information for one day. Results are in a csv format. Easily opened in Excel, Numbers and Google Sheets or imported in other BI systems. Results example