Overview

Once a customer has finished shopping, the Checkout service performs a series of steps to create an order. To accomplish this, the service ensures that the information that is passed from the Site, Cart, Product, Price, and Coupon services are current and valid. The service then passes the details from the cart to the Order service to create an order. If an order creation fails, you can attempt the checkout again. From the list of failed checkouts or checkouts that are successful after a retry, you can retrieve those checkouts based on the:

  • Tenant
  • Checkout ID/tracking number
  • Date range
  • Customer ID
  • Status of the order creation


API Reference

/{tenant}/checkouts

/{tenant}/checkouts

get

Retrieve the checkouts. The caller must have the hybris.checkout_manage scope assigned.

delete

Delete all checkouts of the tenant. The caller must have the hybris.checkout_delete_all scope assigned.

/{tenant}/checkouts/order

/{tenant}/checkouts/order

post

Validate the product inventory, price match, and coupon match. Capture the payment and create an order.

/{tenant}/checkouts/{id}

/{tenant}/checkouts/{id}

get

Retrieve a specific checkout. The caller must have the hybris.checkout_manage scope assigned.

delete

Delete a specific checkout for a given checkout ID. The caller must have the hybris.checkout_manage scope assigned.

/{tenant}/checkouts/{id}/retry

/{tenant}/checkouts/{id}/retry

post

Retry a specific checkout to successfully create an order. The caller must have the hybris.checkout_manage scope assigned.


Events

For more information about events, see the PubSub service documentation.

The topic owner client is: hybris.checkout

Event TypeDescriptionPayloadExample
checkout-failureTriggered when order submission failsschema
{id='92108472-2f34-4d25-bf30-9ea2b2dd8c27', createdAt=1411714974734, tenantId='hybris', serviceName='checkout', topic='hybris.checkout.checkout-failure', payload='{"id":"56391e4f7eae12c135cded5f", "location":"https://api.beta.yaas.io/hybris/checkout/v1/hybris/checkouts/56391e4f7eae12c135cded5f/retry"}'}, "metadata": { "schema": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/checkout-failure-event-v1.1.0" }


Prerequisites

Prior to using the Checkout service, you should complete the following:

Configuring a tax provider, tax code, and discount are optional.
  • Configure the tax provider using the Site service POST /sites/{code}/tax.
  • Configure the fee provider using the Site service POST /sites/{code}/mixins.
  • Configure the payment provider using the Site service POST /sites/{code}/payment.
  • Configure the shipping provider using the Site service POST /sites/{code}/shipping.
  • Create the site code using the Site service POST /sites.
  • Create products for the customer to purchase using the Product service POST /products.
  • Create prices for these products (using the Price service POST /prices.
  • Create fees for the products and/or payment method using the third party fee provider POST /fees.
  • Create tax codes for these products if you want to use a different tax rate than what is configured in the site code using the Tax service POST /tax/codes.
  • Add products to the cart using the Cart service (POST /cartItems).
  • Create discounts to apply to the cart using the Coupon service POST /coupons.
  • Add the discount(s) to the cart using the Cart service POST /carts/{cartId}/discounts.


Checkout Process

The Checkout service has an input schema with all of the information needed for creating an order.

For the Checkout service to successfully check out a cart and create an order, a number of steps must be executed by the service. If the order creation step fails, the checkout status is set to FAILURE and a tracking number (checkoutId) is sent to the customer with details of the order. The service then executes three automatic attempts in 30 minutes to complete the checkout. If the automatic retry attempts are unsuccessful, the administrator can execute a manual retry. The administrator needs to use the hybris.checkout_manage scope to manually retry a checkout on behalf of the customer. If the checkout is successful on one of the retry attempts, the status changes to COMPLETED.

Once a tracking number (checkoutId) is created, the cart is CLOSED.

Checkout statuses

As the checkout process is executed, the checkout object is given a status at the point where the execution stops (whether an order creation is successful or not). The following are the different statuses of the checkout process.

StatusDescription
CREATEDOrder creation was successful after the first checkout attempt.
FAILUREAn error occurred during the order creation step of the checkout process. The checkout process stops, the data is stored, and a tracking number (checkoutId) is sent to the customer. The checkout failture event is issued and the automatic retry mechanism is initiated. An adminstrator can also attempt an manual retry.
RETRY_FAILUREThe checkout process has failed the three automatic retry attempts to create an order.
COMPLETEDThe checkout was successful on one of the retry attempts, the order is created in Order service, and the order ID is returned and stored. This is the final status in the checkout process.

Checkout procedure

This diagram outlines the service execution flow.

graph LR subgraph Checkout Service Process id1((Checkout)) --> Cart_service id1 --> Price_service id1 --> Product_service subgraph Validation Cart_service Price_service Product_service Site_service end id1 --> Site_service subgraph Calculation Cart_Calculation_service end Site_service --> Cart_Calculation_service subgraph Validation & Redemption Coupon_service end Cart_Calculation_service --> Coupon_service subgraph Payment Capture Stripe_Payment_service end Coupon_service --> Stripe_Payment_service subgraph Order Creation Order_service end Stripe_Payment_service --> Order_service Order_service --> id2((Order_created)) end
Checkout service supports customer mixins and Cart service mixins. The cart mixins are passed from the Cart service while the customer mixins are passed from the Customer service or added via an inline schema in the checkout request.

The Checkout service performs these steps:

  1. Validation: It retrieves the site, cart, product, and price information and executes the validation logic and ensures that the correct information is passed from the Site, Cart, Product, and Price services.
    • It validates that the items in the cart are in stock and that there is a price assigned to each item.
    • It validates that the site code exists in the Site service.
    • It validates that the site code is active.
    • It validates the shipping details by checking whether the shipping method (methodId) exists for that site and the shipping amount (amount) is valid for that particular method.
    • It validates whether the actual product exists in the system.
    • It validates that the cart item tax code matches the product tax code.
    • It validates whether the cart is empty.
    • If the request is for the registered user, then it validates equality between the cart's customerId and the hybris-user header value. If the registered user passes the hybris.cart_manage scope, then it will NOT validate the equality between cart's customerId and the hybris-user header value.
    • It validates the equality between the site currency value and cart currency value.

      The next steps are only performed if all the responses are successful. If validation fails, the checkout process stops and the customer receives an error with a comprehensive message indicating what caused the error.
  2. Cart calculation: The Cart Calculation service receives all the data from the Price, Product, Tax/Avalara Tax, Shipping, and fee services to calculation the order's total. Since fees are from a third-party service, the Cart Calculation service needs the item YRN (itemYrn) from the Cart service and the payment method YRN (paymentMethodYrn) from the checkout request body to ensure the correct fee amounts are used when calculating the total.
  3. Coupon validation and redemption: For each discount, a call is made to the Coupon service to check that the discount exists (it can be applied to the current cart and customer) and is valid (it can be applied at the current date, time, cart subtotal, etc.). Then it redeems all the discounts applied to the cart. For each discount, a call to the Coupon service is made to redeem the discount and mark that the coupon has been used. If this step fails, the checkout process stops, the customer's discounts are unredeemed or rolled back, and a comprehensive error message is given to the customer. For more information about discounts, see the Coupon service documentation.
  4. Payment capture: It retrieves the payment provider ID (id) from the Site service and calls the payment provider to capture the payment. The payment can be captured in a single step (immediately when the order is created) or two steps (deferred payment capture where the payment is first authorized and then captured at a later time; usually when the order is shipped). For more information, see the Stripe Payment service documentation. If the immediate payment capture is successful, the payment status is set to success. If the deferred payment feature is enabled and the payment is authorized, then the payment status is set to pending. In both cases, the payment transaction ID and its corresponding status are passed to the Order service during the order creation. If the immediate payment capture or deferred payment capture fails, the checkout process stops, the coupon redemptions are rolled back, and a comprehensive error message is returned.
  5. Order creation: It invokes the Order service to place the order. The Checkout service sends the following information to the Order service:

    • Product details for each item in the cart
    • Site information
    • Customer information
    • Shipping and billing addresses
    • Payment details
    • Fees
    • Taxes
    • Discounts
    • Order total

      If the order is created, an order confirmation ID is sent to the customer and the status is set to CREATED. If it fails, the checkout data is persisted, the cart status is set to CLOSED, the checkout status is set to FAILURE, and a tracking number (checkoutId) is emailed to the customer. For more information on creating an order, see the Order Creation Details document.

If the order is created successfully (an order ID is created), the tracking number (checkoutId) is never used.

If the checkout failed its first attempt, you can attempt the checkout again. For information on retrying the checkout, see Retry a Checkout.


Checkout Retry

If a customer submits a checkout and the checkout process fails, the system returns a checkout ID instead of an order ID. In this case, the Checkout service is configured to automatically resubmit a checkout for a given number of attempts. Aside from the automatic checkout retry, you can also choose to manually resubmit the checkout.

Automatic retry of a failed checkout

The Checkout service is configured to automatically try to complete a checkout when the initial attempt fails. The service is configured to retry the checkout every 10 minutes for 3 attempts. Once the third attempt is complete and the order creation is still not successful, the checkout status is set to RETRY_FAILURE and an email with details of the checkout is sent to the merchant.

For the automatic retry feature to work properly, it needs the following:

When the checkout process fails the initial attempt, the Checkout service publishes the checkout failure topic to the PubSub service. The Checkout service then consumes that information as its indicator to begin the automatic retry. The Checkout service will only commit the event when an order ID has been created after a retry or when the number of retry attempts has been reached and it is still unsuccessful.

The auto retry executes as follows:

  • The Checkout service instance executes a retry of a single checkout ID for 3 attempts before an email is sent to the merchant. The 3 attempts need to be executed for a single checkout ID before the retry process proceeds to the next checkout ID. If the retry process has failed the third checkout attempt, the administrator can execute a manual retry.
  • A checkout ID can only be retried after a 10 minute interval has passed since the last attempt.
You cannot change the values of the number of retry executions or the period between a retry for a single checkout ID.

Manual retry of a failed checkout

The administrator has to take an action in this case, because it means that the customer provided all the information (as expected) for a purchase, but the system failed (for any given reason) to create the order. The retry gives you the opportunity to cover scenarios where the checkout failure was caused by either a service connection issue or business error with the Order service. When the retry operation is successful, the order ID is provided, and the checkout status changes to COMPLETED.

For information on retrying the checkout, see the Retry a Checkout tutorial.


Sorting and Pagination

You can retrieve all the checkout orders that failed on the initial checkout process or that were successful after a retry. You can also sort and set page sizes for the results. When you perform a sort, all of the results are sorted in ascending (default) or descending order based on any of the parameters.

Paging lets you determine how many results you can see on a single page. You can set:

  • the number of results that are visible on a single page (pageSize).
  • the page number you're currently viewing (pageNumber).

By default you are on page one and you can see 1000 results per page. If you set the page number, but do not set the page size, it will show 16 results per page. If you set the page size, but not the page number, the default will display the results on page one.

For an example of how to use the sort and pagination feature, see the Retrieve all checkouts for a list fo criteria section in the Retrieve a Checkout tutorial.


Checkout an Order

Introduction

Once a customer has finished shopping, the next step is to check out the cart and create an order. This process is where the items in the cart are validated, coupon(s) are redeemed (if applicable), the payment is captured, and an order is created. This tutorial shows you how to create a checkout order.

Setup

The following sections show what you need to set up before you can execute any of the calls to this service.

Assertion

Define variable assert:

    assert = chai.assert;

Get an access token

To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:

    API.createClient('oAuth2Service',
    '/oauth2/api.raml');

Now, get the token:

    tenant = projectIdPlaceholder;
    AccessToken = oAuth2Service.token.post({
      'client_id' : clientIdPlaceholder,
      'client_secret':clientSecretPlaceholder,
      'grant_type' : 'client_credentials',
      'token_type': 'Bearer',
      'scope': 'hybris.tenant='+tenant+ ' hybris.site_manage hybris.checkout_manage hybris.cart_manage hybris.shipping_manage hybris.price_manage hybris.product_create hybris.product_update hybris.product_publish'
    });

To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:

    access_token = AccessToken.body.access_token;

Create an API client for all of the services

You need to create an API client for the Site, Stripe Payment, Shipping, Product, Price, Cart, and Checkout services.

    API.createClient('siteService',
    '/site/api.raml');
        API.createClient('stripePaymentService',
    '/stripepayment/api.raml');
    API.createClient('shippingService',
    '/shipping/api.raml');
    API.createClient('productService',
    '/product/api.raml');
    API.createClient('priceService',
    '/price/api.raml');
    API.createClient('cartService',
    '/cart/api.raml');
    API.createClient('checkoutService',
    '/checkout/api.raml');

Create a site

Before you can complete a checkout, you need to create a site and configure the following details:

  • Payment
  • Shipping
  • Tax (optional)
    response = siteService.tenant(tenant).sites.post({
            "code": "canada",
          "name": "Canada",
          "active": true,
          "default": true,
          "languages": [
              "en",
              "fr"
          ],
          "shipToCountries": [
              "US",
              "DE",
              "CA"
          ],
          "homeBase": {
              "address": {
                  "street": "Maisonneuve Ouest",
                  "streetNumber": "999",
                  "zipCode": "H3A 3L4",
                  "city": "Montreal",
                  "country": "CA",
                  "state": "Quebec"
              }
          },
          "currency": "CAD",
          "tax": [
              {
                  "id": "FLATRATE",
                  "name": "Flatrate Tax Service",
                  "serviceType": "urn:x-yaas:service:tax",
                  "serviceUrl": "https://api.stage.yaas.io/hybris/tax/v1",
                  "active": true,
                  "configuration": {
                      "public": {
                          "rate": 5,
                          "label": "Old Label",
                          "code": "FLAT",
                          "name": "Tax Flat Rate",
                          "description": "Tax Flat Rate description",
                          "included": false
                      }
                  }
              }
          ],
          "payment": [
              {
                  "id": "stripe",
                  "name": "Stripe Payment Service",
                  "serviceType": "urn:x-yaas:service:payment",
                  "serviceUrl": "https://payment-mock.us-east.stage.cf.yaas.io",
                  "active": true,
                  "configuration": {
                      "restricted": {
                          "privateKey": "[:]",
                          "mockPayment": true,
                          "stripeConnect": {
                              "liveMode": false
                          }
                      }
                  }
              }
          ],
          "shipping": [
              {
                  "id": "fedex-2dayground",
                  "name": "FedEx Standard",
                  "serviceType": "urn:x-yaas:service:shipping",
                  "serviceUrl": "https://api.stage.yaas.io/hybris/shipping/v1",
                  "active": true
              }
          ]
        }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json'
        }
    });
    assert.equal(response.status, 201);
    response.body;
        response = shippingService.tenant(tenant).site('testSite').zones.post({
          "id": "germany",
          "name": "Germany",
          "shipTo": [
              "DE"
          ],
          "default": true
        }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json',
              'Content-Language' : 'en_US'
        }
    });
    assert.equal(response.status, 201);
    response.body;
        response = shippingService.tenant(tenant).site('canada').zones.zoneId('germany').methods.post({
          "id": "fedex-2dayground",
          "name": "FedEx Standard",
          "active": true,
          "maxOrderValue": {
              "amount": 100,
              "currency": "CAD"
          },
          "fees": [
              {
                  "cost": {
                      "amount": 4.99,
                      "currency": "CAD"
                  },
                  "minOrderValue": {
                      "amount": 2,
                      "currency": "CAD"
                  }
              }
          ]
        }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json',
              'Content-Language' : 'en_US'
        }
    });
    assert.equal(response.status, 201);
    response.body;

Create a product

After you create and configure the tenant's site, you need to create products for the store. For this example, create a t-shirt.

         response = productService.tenant(tenant).products.post({
            "name": "sku11111474572994867",
          "description": "sku11111474572994867",
          "sku": "SKUsku11111474572994867",
          "code": "SKUsku11111474572994867",
          "metadata": {
              "mixins": {
                  "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
              },
              "variants": {
                  "options": {
                      "t-shirt": "https://api.stage.yaas.io/hybris/schema/v1/projectuiv3/tshirt_variant-version1.json"
                  }
              }
          },
          "mixins": {
              "inventory": {
                  "inStock": true
              }
          }
        }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json',
              'Content-Language' : 'en_US'
        }
        }
    );
    assert.equal(response.status, 201);
    productId1 = response.body.id;
    response;

Once the product is created, you need to publish it to your storefront before a price can be created for this product.

response = productService.tenant(tenant).products.productId(productId1).put({
            "published": true
        }, {
          headers: {
              'Authorization': 'Bearer ' + access_token,
              'Content-Type' : 'application/json',
              'Content-Language' : 'en_US'
          },
          query: {
            'partial': 'true'
          }
                }
    );
    assert.equal(response.status, 200);
    response;

Create a price

Now create a price for the t-shirt.

         response = priceService.tenant(tenant).prices.post({
        "originalAmount": 11.5,
        "currency": "CAD",
        "productId": productId1
        }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json'
        }
        }
    );
    assert.equal(response.status, 201);
    priceId1 = response.body.id;
    response;

Create a cart with an item

In order for the customer to add items to their cart, a cart needs to be created.

        response = cartService.tenant(tenant).carts.post({
          "currency": "CAD",
          "channel": {
              "name": "yaas-storefront",
              "source": "shops.yaas.io",
              "siteCode": "canada"
          }
        }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json'
        }
    });
    assert.equal(response.status, 201);
    cartId1 = response.body.cartId;
    response.body;

Now add the t-shirt to the newly created cart.

        response = cartService.tenant(tenant).carts.cartId(cartId1).items.post({
        "quantity": 10,
        "price": {
            "yrn": "urn:yaas:hybris:price:id:myshop;57e432c6090a83001d721fbb",
            "originalAmount": 11.5,
            "effectiveAmount": 11.5,
            "currency": "CAD",
            "priceId": priceId1
        },
        "metadata": {
            "mixins": {
                "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
            }
        },
        "mixins": {
            "inventory": {
                "inStock": false
            }
        },
        "product": {
            "id": productId1,
            "yrn": "urn:yaas:hybris:product:product:myshop;576bf71ebfe5c2001df3f96b",
            "sku": "57e432c48d0c98001dd6e572",
            "name": "57e432c48d0c98001dd6e572",
            "description": "57e432c48d0c98001dd6e572",
            "images": [
                {
                    "id": "2345678987654",
                    "url": "http://localhost/img0157e432c48d0c98001dd6e572.png"
                }
            ]
        }
      }, {
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json'
        }
    });
    assert.equal(response.status, 201);
    response.body;

Checkout the cart

When the customer has finished shopping, they need to complete a checkout so an order can be created. Now check out the cart.

Headers

Authorization: You need to provide a proper manage scope that enables the user to perform these operations. For example, for authorization purposes you could use an Authorization header to send a valid OAuth 2.0 access token. For an overview of the authorization and authentication used in SAP Hybris services, see Authorization.

Accept-Language: This header provides the preferred languages to the Order service and Product service. You need to separate the list of languages and the different regions with a comma. For example, de, en-gb;q=0.8, en;q=0.7. The Order service uses this list for any order-related emails. The Product service uses this list to retrieve the product content (for example, the name and description) in the desired language. If this header is not provided, English (en) is the default.

Body

payment: The payment providers are defined in the Site service for each site. It is possible to have more than one active payment provider per site. To support the different payment providers, the payment customAttributes is passed from the Checkout service to the payment provider. You should verify the payment provider documentation to confirm which attribute should be passed to the checkout payload as the customAttributes.

  • You cannot place an order with a cart that contains a product with a noncurrent date range.
  • You cannot place an order with a cart that contains a product with a price that has a volume constraint if the quantity of the product does not match the volume range.
    response = checkoutService.tenant(tenant).checkouts.order.post({
          "payment": {
              "paymentId": "stripe",
              "customAttributes": {
                  "token": "tok_18wczs4xLYxmKjcz1mTEbfXu"
              }
          },
          "addresses": [
              {
                  "zipCode": "32587",
                  "country": "DE",
                  "streetNumber": "86",
                  "city": "Munchen",
                  "contactName": "Peter Priceless",
                  "street": "Nymphenburger",
                  "streetAppendix": "west",
                  "companyName": "Hybris",
                  "state": "DE",
                  "contactPhone": "49-89 890 65 555",
                  "type": "BILLING"
              },
              {
                  "zipCode": "32547",
                  "country": "DE",
                  "streetNumber": "86",
                  "city": "Munchen",
                  "contactName": "Peter Priceless",
                  "street": "Nymphenburger",
                  "streetAppendix": "west",
                  "companyName": "Hybris",
                  "state": "DE",
                  "contactPhone": "49-89 890 65 555",
                  "type": "SHIPPING"
              }
          ],
          "shipping": {
              "methodId": "fedex-2dayground",
              "amount": 4.99,
              "zoneId": "germany"
          },
          "totalPrice": 571.2,
          "cartId": cartId1,
          "currency": "EUR",
          "customer": {
              "id": "tp12@hybristest.com",
              "yrn": "urn:yaas:hybris:customer:customer:myshop;576bf71ebfe5c2001df3f96b",
              "name": "John S. Smith",
              "title": "Mr.",
              "firstName": "John",
              "middleName": "S.",
              "lastName": "Smith",
              "email": "tp12@hybristest.com",
              "company": "SAP"
          }
           },{
        headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json'
        }
    });
    assert.equal(response.status, 200);
    checkoutCodeId = response.body.id;
    response.body;

If the order creation is successful, the order information is passed from the Checkout service to the Order service. If the checkout process fails, a checkout ID is created, the cart's information is persisted, and the Checkout service will attempt to complete the checkout again. For more information on retrying a checkout, see the Checkout Retry page or the Retry a Checkout tutorial.


Retrieve a Checkout

You can retrieve all the checkouts that have either failed the initial checkout process or that were successful after a retry. Typically a checkout fails when the Order service is down.

You can retrieve the checkouts based on the following parameters:

  • A specific tenant.
  • A specific tracking number (checkoutId).
  • All checkouts according to these query parameters:
    • customerId: All checkouts for a specific customer.
    • orderCreated: All checkouts with a successful/unsuccessful order creation.
    • modifiedFrom: All checkouts starting from a specific date.
    • modifiedTo: All checkouts up to a specific date.
    • checkoutCompleted: All successful checkouts after a failed initial checkout attempt.

The retrieve request supports sorting by using the sort query parameter. If multiple sort attributes are present then the response will contain the data based on first sort attribute criteria.

It also supports pagination using the pageSize and pageNumber query parameters.

Since a checkout order only fails if the Order service is down, this tutorial cannot be shown as an interactive tutorial.

Retrieve all checkouts for a tenant

You can retrieve all the checkouts for a specific tenant. This request is based on the hybris-tenant header.

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/checkout/v1/{tenant}/checkouts

Response

  • Status code: 200
  • Example: The response body contains a list or an array of all checkouts for a given tenant.
[
{
    "id": "587e3310c70a5b001d956bc9",
    "yrn": "urn:yaas:hybris:checkout:checkout:checkoutsmoke;587e3310c70a5b001d956bc9",
    "cart": {
        "id": "587e3306b09fd0001de76003",
        "yrn": "urn:yaas:hybris:cart:cart:checkoutsmoke;587e3306b09fd0001de76003",
        "currency": "EUR",
        "siteCode": "test_site_checkout_acceptance1484665603857",
        "totalPrice": 464.99,
        "subTotalPrice": 460.0,
        "shipping": {
            "methodId": "fedex-2dayground",
            "zoneId": "germany",
            "amount": 4.99
        },
        "totalUnitsCount": 40,
        "totalTax": 155.0,
        "taxDescription": "Tax Flat Rate description",
        "totalDiscount": 0.0,
        "cartItems": [
            {
                "id": "0",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;0",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e3307ca417e001d17e1a3",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e3307ca417e001d17e1a3",
                    "name": "sku111114846656063031",
                    "description": "sku111114846656063031",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e3307ca417e001d17e1a4",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e3307ca417e001d17e1a4",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1",
                        "firstMixin": {
                            "type": "object",
                            "properties": {
                                "firstProperty": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "firstProperty"
                            ],
                            "$schema": "http://json-schema.org/draft-04/schema#"
                        }
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    },
                    "firstMixin": {
                        "firstProperty": "Simple Comment"
                    }
                }
            },
            {
                "id": "1",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;1",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e330816fbb4001d3aa20a",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e330816fbb4001d3aa20a",
                    "name": "sku111114846656063032",
                    "description": "sku111114846656063032",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e3309ca417e001d17e1a5",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e3309ca417e001d17e1a5",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    }
                }
            },
            {
                "id": "2",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;2",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e3309ca417e001d17e1a6",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e3309ca417e001d17e1a6",
                    "name": "sku111114846656063033",
                    "description": "sku111114846656063033",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e330aca417e001d17e1a7",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e330aca417e001d17e1a7",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    }
                }
            },
            {
                "id": "3",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;3",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e330bc70a5b001d956bc8",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e330bc70a5b001d956bc8",
                    "name": "sku111114846656063034",
                    "description": "sku111114846656063034",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e330bb09fd0001de76006",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e330bb09fd0001de76006",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    }
                }
            }
        ],
        "taxAggregate": {
            "lines": [
                {
                    "name": "Tax Flat Rate",
                    "amount": 155.0,
                    "rate": 50.0,
                    "taxable": 464.99
                }
            ]
        },
        "metadata": {
            "mixins": {
                "firstMixin": {
                    "type": "object",
                    "properties": {
                        "firstProperty": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "firstProperty"
                    ],
                    "$schema": "http://json-schema.org/draft-04/schema#"
                },
                "payments": "https://api.stage.yaas.io/hybris/checkout/v1/meta-data/schemas/fees.json"
            }
        },
        "mixins": {
            "firstMixin": {
                "firstProperty": "Simple Comment"
            },
            "payments": {
                "total": {
                    "subTotal": 0.0,
                    "totalTax": 0.0,
                    "total": 0.0
                }
            }
        }
    },
    "status": "FAILURE",
    "customer": {
        "title": "Mr.",
        "firstName": "John",
        "middleName": "S.",
        "lastName": "Smith",
        "email": "tp12@hybristest.com",
        "company": "SAP",
        "yrn": "urn:yaas:hybris:customer:customer:myshop;576bf71ebfe5c2001df3f96b",
        "metadata": {
            "mixins": {
                "firstMixin": {
                    "type": "object",
                    "properties": {
                        "firstProperty": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "firstProperty"
                    ],
                    "$schema": "http://json-schema.org/draft-04/schema"
                }
            }
        },
        "mixins": {
            "firstMixin": {
                "firstProperty": "Simple Comment"
            }
        }
    },
    "metadata": {
        "createdAt": "2017-01-17T15:06:56.313Z",
        "modifiedAt": "2017-01-17T15:06:56.313Z",
        "version": 1
    },
    "addresses": [
        {
            "contactName": "Peter Priceless",
            "companyName": "Hybris",
            "street": "Nymphenburger",
            "streetNumber": "86",
            "streetAppendix": "west",
            "zipCode": "32587",
            "city": "Munchen",
            "country": "DE",
            "state": "DE",
            "contactPhone": "49-89 890 65 555",
            "type": "BILLING",
            "metadata": {
                "mixins": {
                    "BillingAddress": {
                        "type": "object",
                        "properties": {
                            "additionalComments": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "additionalComments"
                        ],
                        "$schema": "http://json-schema.org/draft-04/schema#"
                    }
                }
            },
            "mixins": {
                "BillingAddress": {
                    "additionalComments": "Please use my VISA."
                }
            }
        },
        {
            "contactName": "Peter Priceless",
            "companyName": "Hybris",
            "street": "Nymphenburger",
            "streetNumber": "86",
            "streetAppendix": "west",
            "zipCode": "32547",
            "city": "Munchen",
            "country": "DE",
            "state": "DE",
            "contactPhone": "49-89 890 65 555",
            "type": "SHIPPING",
            "metadata": {
                "mixins": {
                    "ShippingAddress": {
                        "type": "object",
                        "properties": {
                            "secondaryContactPhone": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "secondaryContactPhone"
                        ],
                        "$schema": "http://json-schema.org/draft-04/schema#"
                    }
                }
            },
            "mixins": {
                "ShippingAddress": {
                    "secondaryContactPhone": "+86 334 0033 9934"
                }
            }
        }
    ],
    "order": {
        "status": "FAILURE",
        "error": "Something went wrong while processing the request. The error has been logged under code 20170117_150656_115_bvmbfil."
    },
    "payment": {
        "status": "SUCCESS",
        "paidAmount": 464.99,
        "currency": "EUR",
        "transactionId": "ch_16jEki4xLYxmKjczib6G9sDR",
        "paymentMethod": "mockPayment"
    },
    "retryAttempts": 0
}
]

Retrieve a checkout for a given checkout ID

You can retrieve a checkout for a specific tracking number (checkoutId). This request is based on the hybris-tenant header.

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/checkout/v1/{tenant}/checkouts/{id}

Response

  • Status code: 200
  • Example: The response body contains all of the checkout information.
{
    "id": "587e3310c70a5b001d956bc9",
    "yrn": "urn:yaas:hybris:checkout:checkout:checkoutsmoke;587e3310c70a5b001d956bc9",
    "cart": {
        "id": "587e3306b09fd0001de76003",
        "yrn": "urn:yaas:hybris:cart:cart:checkoutsmoke;587e3306b09fd0001de76003",
        "currency": "EUR",
        "siteCode": "test_site_checkout_acceptance1484665603857",
        "totalPrice": 464.99,
        "subTotalPrice": 460.0,
        "shipping": {
            "methodId": "fedex-2dayground",
            "zoneId": "germany",
            "amount": 4.99
        },
        "totalUnitsCount": 40,
        "totalTax": 155.0,
        "taxDescription": "Tax Flat Rate description",
        "totalDiscount": 0.0,
        "cartItems": [
            {
                "id": "0",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;0",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e3307ca417e001d17e1a3",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e3307ca417e001d17e1a3",
                    "name": "sku111114846656063031",
                    "description": "sku111114846656063031",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e3307ca417e001d17e1a4",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e3307ca417e001d17e1a4",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1",
                        "firstMixin": {
                            "type": "object",
                            "properties": {
                                "firstProperty": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "firstProperty"
                            ],
                            "$schema": "http://json-schema.org/draft-04/schema#"
                        }
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    },
                    "firstMixin": {
                        "firstProperty": "Simple Comment"
                    }
                }
            },
            {
                "id": "1",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;1",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e330816fbb4001d3aa20a",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e330816fbb4001d3aa20a",
                    "name": "sku111114846656063032",
                    "description": "sku111114846656063032",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e3309ca417e001d17e1a5",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e3309ca417e001d17e1a5",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    }
                }
            },
            {
                "id": "2",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;2",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e3309ca417e001d17e1a6",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e3309ca417e001d17e1a6",
                    "name": "sku111114846656063033",
                    "description": "sku111114846656063033",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e330aca417e001d17e1a7",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e330aca417e001d17e1a7",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    }
                }
            },
            {
                "id": "3",
                "yrn": "urn:yaas:hybris:cart:cart-item:checkoutsmoke;587e3306b09fd0001de76003;3",
                "quantity": 10.0,
                "taxCode": "FLAT",
                "product": {
                    "id": "587e330bc70a5b001d956bc8",
                    "yrn": "urn:yaas:hybris:product:product:checkoutsmoke;587e330bc70a5b001d956bc8",
                    "name": "sku111114846656063034",
                    "description": "sku111114846656063034",
                    "metadata": {
                        "mixins": {
                            "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                        }
                    },
                    "mixins": {
                        "inventory": {
                            "inStock": true
                        }
                    }
                },
                "unitPrice": {
                    "priceId": "587e330bb09fd0001de76006",
                    "yrn": "urn:yaas:hybris:price:id:myshop;587e330bb09fd0001de76006",
                    "originalAmount": 11.5,
                    "value": 11.5,
                    "currency": "EUR"
                },
                "itemPrice": 115.0,
                "itemTaxes": [
                    {
                        "name": "Tax Flat Rate",
                        "value": 38.33,
                        "rate": 50.0
                    }
                ],
                "metadata": {
                    "mixins": {
                        "inventory": "https://api.beta.yaas.io/hybris/schema/v1/hybriscommerce/inventorySchema-v1"
                    }
                },
                "mixins": {
                    "inventory": {
                        "inStock": false
                    }
                }
            }
        ],
        "taxAggregate": {
            "lines": [
                {
                    "name": "Tax Flat Rate",
                    "amount": 155.0,
                    "rate": 50.0,
                    "taxable": 464.99
                }
            ]
        },
        "metadata": {
            "mixins": {
                "firstMixin": {
                    "type": "object",
                    "properties": {
                        "firstProperty": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "firstProperty"
                    ],
                    "$schema": "http://json-schema.org/draft-04/schema#"
                },
                "payments": "https://api.stage.yaas.io/hybris/checkout/v1/meta-data/schemas/fees.json"
            }
        },
        "mixins": {
            "firstMixin": {
                "firstProperty": "Simple Comment"
            },
            "payments": {
                "total": {
                    "subTotal": 0.0,
                    "totalTax": 0.0,
                    "total": 0.0
                }
            }
        }
    },
    "status": "FAILURE",
    "customer": {
        "title": "Mr.",
        "firstName": "John",
        "middleName": "S.",
        "lastName": "Smith",
        "email": "tp12@hybristest.com",
        "company": "SAP",
        "yrn": "urn:yaas:hybris:customer:customer:myshop;576bf71ebfe5c2001df3f96b",
        "metadata": {
            "mixins": {
                "firstMixin": {
                    "type": "object",
                    "properties": {
                        "firstProperty": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "firstProperty"
                    ],
                    "$schema": "http://json-schema.org/draft-04/schema"
                }
            }
        },
        "mixins": {
            "firstMixin": {
                "firstProperty": "Simple Comment"
            }
        }
    },
    "metadata": {
        "createdAt": "2017-01-17T15:06:56.313Z",
        "modifiedAt": "2017-01-17T15:06:56.313Z",
        "version": 1
    },
    "addresses": [
        {
            "contactName": "Peter Priceless",
            "companyName": "Hybris",
            "street": "Nymphenburger",
            "streetNumber": "86",
            "streetAppendix": "west",
            "zipCode": "32587",
            "city": "Munchen",
            "country": "DE",
            "state": "DE",
            "contactPhone": "49-89 890 65 555",
            "type": "BILLING",
            "metadata": {
                "mixins": {
                    "BillingAddress": {
                        "type": "object",
                        "properties": {
                            "additionalComments": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "additionalComments"
                        ],
                        "$schema": "http://json-schema.org/draft-04/schema#"
                    }
                }
            },
            "mixins": {
                "BillingAddress": {
                    "additionalComments": "Please use my VISA."
                }
            }
        },
        {
            "contactName": "Peter Priceless",
            "companyName": "Hybris",
            "street": "Nymphenburger",
            "streetNumber": "86",
            "streetAppendix": "west",
            "zipCode": "32547",
            "city": "Munchen",
            "country": "DE",
            "state": "DE",
            "contactPhone": "49-89 890 65 555",
            "type": "SHIPPING",
            "metadata": {
                "mixins": {
                    "ShippingAddress": {
                        "type": "object",
                        "properties": {
                            "secondaryContactPhone": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "secondaryContactPhone"
                        ],
                        "$schema": "http://json-schema.org/draft-04/schema#"
                    }
                }
            },
            "mixins": {
                "ShippingAddress": {
                    "secondaryContactPhone": "+86 334 0033 9934"
                }
            }
        }
    ],
    "order": {
        "status": "FAILURE",
        "error": "Something went wrong while processing the request. The error has been logged under code 20170117_150656_115_bvmbfil."
    },
    "payment": {
        "status": "SUCCESS",
        "paidAmount": 464.99,
        "currency": "EUR",
        "transactionId": "ch_16jEki4xLYxmKjczib6G9sDR",
        "paymentMethod": "mockPayment"
    },
    "retryAttempts": 0
}

Retrieve all checkouts for a list of criteria

You can retrieve all of the checkout orders based on various criteria. This example uses the customerId, orderCreated, checkoutCompleted, modifiedFrom, and modifiedTo attributes. It also shows how you can sort the results in descending order based on the retryAttempts attribute and set the pagination to display two results per page. For more information on sorting and pagination, see the Sorting and Pagination page.

Request

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/checkout/v1/{tenant}/checkouts?checkoutCompleted=false&customerId=tp12@hybristest.com&modifiedFrom=2017-01-17T15:06:56.313Z&modifiedTo=2017-01-17T15:06:56.313Z&orderCreated=false&pageNumber=1&pageSize=2&sort=retryAttemps:desc

Response

  • Status code: 200


Retry a Checkout

The merchant can resubmit a checkout for a specific tenant and checkout ID. This request is based on the hybris-tenant header. The following example is for both an automatic and manual retry. For more information about retrying a checkout, see the Checkout Retry page.

Since a checkout order only fails if the Order service is down, this tutorial cannot be shown as an interactive tutorial.

Request

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/checkout/v1/{tenant}/checkouts/{id}/retry

Response

  • Status code: 200
  • Example: The response body contains the order ID.
{
      "orderId" : "order00001"
}


Error Codes

For more information about error codes, see the API Reference.


Glossary

TermDescription
discountA percentage or dollar amount that is subtracted from the product's original price or from the cart's total.
fee providerA service that lets the merchant set fees for a given item or payment method.
orderOnce a customer has finished shopping and the items in the cart are checked out and processed.
payment captureWhen the service makes a call to the third-party payment provider and charges the cost of the order to the customer's payment card.
payment providerA service that lets the customer pay for their order. An example of a payment provider is Stripe.
productAn object that belongs to the store.
shipping providerA service that ships an order to the customer. An example of a shipping provider is FedEx.
site codeA code you assign to a specific site, such as 'US' for the United States. The site code is configured in the Site service.
tax codeA code created in the Tax service that is then assigned to a product.
tax providerA service that calculates the taxes to be applied on a customer's order.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.