My Shopping Cart Resource

Introduction

The my shopping cart resource provides an interface to create and fill a shopping cart. After creating and filling the shopping cart via the API, the checkout may then be performed on the storefront of the customer. For access to the shopping cart you have to create a session token.

Add item to cart

To add items to the cart, you have to post it the /items sub resource. You can post directly to the sub resource without creating a previous shopping cart:

The url for creating items is https://api.openpublishing.com/resource/v3/my_shopping_cart/items. It accepts the following HTTP methods:

POST Create new item.

When posting an item, only the fields EAN and quantity are writeable. All other fields are calculated in the backend.

{
   "ean": "9781234567890",
   "quantity": 2
}

Retrieve my open cart of session

Url: https://api.openpublishing.com/resource/v3/my_shopping_cart

Available HTTP methods:

GET to obtain current shopping cart of session. A shopping cart will be created implicitely.
PUT modify shopping cart. It will be implicitely created if not present.
DELETE: Delete shopping cart.

{
    "_id": 1,
    "_links": {
        "items": "https://api.openpublishing.com/resource/v3/my_shopping_cart/items",
        "self": "https://api.openpublishing.com/resource/v3/my_shopping_cart",
        "total": "https://api.openpublishing.com/resource/v3/my_shopping_cart/total",
        "checkout": "https://api.openpublishing.com/resource/v3/my_shopping_cart/checkout"
    },
    "billing_address": {
       "additional_information": "2. Stock",
       "city": "München",
       "company": "Open Publishing GmbH",
       "country": "DE",
       "email": "test@example.com",
       "first_name": "John",
       "last_name": "Doe",
       "phone_number": "+49 89 1234567890",
       "state": null,
       "street": "Trappentreustraße 1",
       "zip": "80339"
    },
    "created": "2021-03-01 14:00:00",
    "realm": {
      "_id": 23,
      "name": "testpublisher",
      "screenname": "Test Publisher"
    },
    "shipping_address": {
       "additional_information": "Rückgebäude",
       "company": null,
       "city": "München",
       "country": "DE",
       "first_name": "John",
       "last_name": "Doe",
       "phone_number": null,
       "state": null,
       "street": "Marktplatz 12",
       "zip": "81479"
    }
}

Items of the cart

Url: https://api.openpublishing.com/resource/v3/my_shoppingcart/items

Available HTTP methods: GET to obtain list of all items of shopping cart.

{
    "_links": {
        "self": "https://api.openpublishing.com/resource/v3/my_shopping_carts/items"
    },
    "items": [
        {
            "_links": {
                "self": "https://api.openpublishing.com/resource/v3/my_shopping_carts/items/42",
            },
           "_id": "1469",
           "cover_url": "https://cdn.julius.dev.openpublishing.com/images/cover/brand/e-book/1/1387_thumb.jpg",
           "ean": "9781234567890",
           "format": "book",
           "quantity": 10,
           "title": "Example publication",
           "total_gross": 19990,
           "total_gross_currency": "EUR",
           "total_net": 18682,
           "total_net_currency": "EUR",
           "total_vat": 1308,
           "total_vat_currency": "EUR",
           "unit_price_gross": 131,
           "unit_price_gross_currency": "EUR",
           "unit_price_net": 1868,
           "unit_price_net_currency": "EUR",
           "unit_vat": 131,
           "unit_vat_currency": "EUR",
           "vat_percentage": 7.0
        }
   ]
}

The URL for a single item is https://api.openpublishing.com/resource/v3/my_shopping_carts/items/42. It accepts the following HTTP Methods:

GET Get single item
PUT Modify item.
DELETE Delete item from shopping cart.

Cover URL

The URL specified within cover_url points to a cover thumbnail.

EAN

EAN is the EAN of the added product.

Title

title is the title of the added product.

Format

format of the added item. Values can be book or ebook.

Quantity

quantity is the quantity of added items.

Single unit price gross net and VAT.

unit_price_net, unit_price_net_currency specifies thet net price per unit. unit_vat and unit_vat_currency the VAT per unit. unit_price_gross and unit_price_gross_currency the gross price of per unit. The currencies are reported with ISO 4217 currency codes.

Total price gross net and VAT.

total_net, total_net_currency specifies thet net price for all units. total_vat and total_vat_currency the VAT for all units. total_gross and total_gross_currency the gross price for all units. The currencies are reported with ISO 4217 currency codes.

Vat percentage

vat_percentage is the factor for VAT calculation in percent.

Checkout

After all items have been added to the cart, the user needs to be redirected to the checkout process.

URL https://api.openpublishing.com/resource/v3/my_shopping_cart/checkout. It accepts the following HTTP methods:

GET Retrieve the URL for the checkout.

{
    "_links": {
        "self": "https://api.openpublishing.com/resource/v3/my_shopping_carts/checkout",
    },
    "checkout_url": "https://testpublisher.openpublishing.com/shoppingcart?checkout_token=XXX",
    "checkout_url_addresses": "https://testpublisher.openpublishing.com/shoppingcart?redirect=addresses&checkout_token=XXX",
    "valid_until": 1623140624
}

checkout_url is the URL for proceeding with the checkout. checkout_url_addresses is the URL for directly proceeding with invoice address / shipping address. valid_until is the UNIX timestamp when the checkout_token expires.