io.sphere.sdk.carts

Enum TaxMode

java.lang.Object

java.lang.Enum<TaxMode>

io.sphere.sdk.carts.TaxMode

All Implemented Interfaces:

SphereEnumeration, Serializable, Comparable<TaxMode>

public enum TaxMode
extends Enum<TaxMode>
implements SphereEnumeration

Enum Constant Summary

Enum Constants

Enum Constant and Description
DISABLED No taxes are added to the cart.
EXTERNAL The tax rates are set externally.
EXTERNAL_AMOUNT The tax amounts and the tax rates as well as the tax portions are set externally per ExternalTaxAmountDraft.
PLATFORM The tax rates are selected by the system from the tax categories based on the cart shipping address.

Method Summary

Modifier and Type	Method and Description
static TaxMode	ofSphereValue(String value)
static TaxMode	valueOf(String name) Returns the enum constant of this type with the specified name.
static TaxMode[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.sphere.sdk.models.SphereEnumeration

findBySphereName, name, toSphereName

Enum Constant Detail

PLATFORM

public static final TaxMode PLATFORM

The tax rates are selected by the system from the tax categories based on the cart shipping address.

EXTERNAL

public static final TaxMode EXTERNAL

The tax rates are set externally. A cart with this tax mode can only be ordered if all line items, all custom line items and the shipping method have an external tax rate set.

Create a cart with external tax mode

Cart creation with line item

withProductOfPrices(client(), singletonList(PriceDraft.of(EURO_10)), (Product product) -> {
    final String taxRateName = "special tax";
    final double rate = 0.20;
    final ExternalTaxRateDraft externalTaxRate =
            ExternalTaxRateDraftBuilder.ofAmount(rate, taxRateName, DE).build();
    final int quantity = 22;
    final int variantId = 1;
    final LineItemDraft itemDraft = LineItemDraft.of(product, variantId, quantity)
            .withExternalTaxRate(externalTaxRate);
    final CartDraftDsl cartDraft = CartDraft.of(EUR)
            .withTaxMode(TaxMode.EXTERNAL)//important
            .withCountry(DE)
            .withShippingAddress(Address.of(DE))
            .withLineItems(singletonList(itemDraft));
    final CartCreateCommand cmd = CartCreateCommand.of(cartDraft);

    final Cart cart = client().executeBlocking(cmd);

    assertThat(cart.getTaxMode()).isEqualTo(TaxMode.EXTERNAL);
    final LineItem lineItem = cart.getLineItems().get(0);

    softAssert(s -> {
        final TaxRate taxRate = lineItem.getTaxRate();
        s.assertThat(taxRate.getName()).isEqualTo(taxRateName);
        s.assertThat(taxRate.getAmount()).isEqualTo(rate);
        s.assertThat(taxRate.getCountry()).isEqualTo(DE);
        s.assertThat(taxRate.getId()).as("tax rate id").isNull();
        s.assertThat(taxRate.getSubRates()).as("sub rates").isEmpty();
        s.assertThat(lineItem.getTotalPrice()).as("lineItem totalPrice").isEqualTo(MoneyImpl.of(220, EUR));
        s.assertThat(cart.getTotalPrice()).as("cart totalPrice").isEqualTo(MoneyImpl.of(220, EUR));
        final TaxedPrice taxedPrice = cart.getTaxedPrice();
        s.assertThat(taxedPrice.getTotalGross()).as("gross").isEqualTo(MoneyImpl.of(264, EUR));
        s.assertThat(taxedPrice.getTotalNet()).as("net").isEqualTo(MoneyImpl.of(220, EUR));
    });
});
See the test code.

Create empty cart

final CartDraftDsl cartDraft = CartDraft.of(EUR)
        .withTaxMode(TaxMode.EXTERNAL);//important

final Cart cart = client().executeBlocking(CartCreateCommand.of(cartDraft));

assertThat(cart.getTaxMode()).isEqualTo(TaxMode.EXTERNAL);
See the test code.

Add a LineItem with an external tax rate

withProductOfPrices(client(), singletonList(PriceDraft.of(EURO_10)), (Product product) -> {
    final CartDraft draft = CartDraft.of(EUR).withTaxMode(TaxMode.EXTERNAL);
    withCartDraft(client(), draft, (Cart cart) -> {
        final int quantity = 3;
        final int variantId = product.getMasterData().getStaged().getMasterVariant().getId();
        final String taxRateName = "special tax";
        final double rate = 0.20;
        final List<SubRate> subRates = asList(SubRate.of("foo", 0.11), SubRate.of("bar", 0.09));
        final ExternalTaxRateDraft externalTaxRate =
                ExternalTaxRateDraftBuilder.ofAmount(rate, taxRateName, DE)
                        .subRates(subRates)
                        .build();
        final AddLineItem updateAction = AddLineItem.of(product, variantId, quantity)
                .withExternalTaxRate(externalTaxRate);
        final Cart cartWithLineItem = client().executeBlocking(CartUpdateCommand.of(cart, updateAction));

        final LineItem lineItem = cartWithLineItem.getLineItems().get(0);
        final TaxRate taxRate = lineItem.getTaxRate();
        assertThat(taxRate.getSubRates()).isEqualTo(subRates);
        assertThat(taxRate.getCountry()).isEqualTo(DE);
        assertThat(taxRate.getId()).isNull();
        assertThat(taxRate.getName()).isEqualTo(taxRateName);
        assertThat(taxRate.getAmount()).isEqualTo(0.2);
        assertThat(taxRate.isIncludedInPrice()).isFalse();
        assertThat(lineItem.getTotalPrice()).isEqualTo(MoneyImpl.ofCents(3000, "EUR"));
        assertThat(lineItem.getTaxedPrice().getTotalNet()).isEqualTo(MoneyImpl.ofCents(3000, "EUR"));
        assertThat(lineItem.getTaxedPrice().getTotalGross()).isEqualTo(MoneyImpl.ofCents(3600, "EUR"));

        return cartWithLineItem;
    });
});
See the test code.

Error case when the cart does not have the external tax but a line item is added

withProductOfPrices(client(), singletonList(PriceDraft.of(EURO_10)), (Product product) -> {
    final CartDraft draft = CartDraft.of(EUR); // Uses the Platform TaxMode by default
    withCartDraft(client(), draft, (Cart cart) -> {
        final int quantity = 3;
        final int variantId = product.getMasterData().getStaged().getMasterVariant().getId();
        final String taxRateName = "special tax";
        final double taxRate = 0.20;
        final List<SubRate> subRates = asList(SubRate.of("foo", 0.11), SubRate.of("bar", 0.09));
        final ExternalTaxRateDraft externalTaxRate =
                ExternalTaxRateDraftBuilder.ofAmount(taxRate, taxRateName, DE)
                        .subRates(subRates)
                        .build();
        final AddLineItem updateAction = AddLineItem.of(product, variantId, quantity)
                .withExternalTaxRate(externalTaxRate);

        final Throwable throwable = catchThrowable(() -> client().executeBlocking(CartUpdateCommand.of(cart, updateAction)));

        //the error message is sth. like "Cannot set an external tax rate on a cart with taxMode 'Platform'."
        assertThat(throwable).isInstanceOf(ErrorResponseException.class);

        return cart;
    });
});
See the test code.

Add a LineItem and add the external tax rate later

withProductOfPrices(client(), singletonList(PriceDraft.of(EURO_10)), (Product product) -> {
    final CartDraft draft = CartDraft.of(EUR).withTaxMode(TaxMode.EXTERNAL);
    withCartDraft(client(), draft, (Cart cart) -> {
        final int quantity = 3;
        final int variantId = product.getMasterData().getStaged().getMasterVariant().getId();
        final AddLineItem updateAction = AddLineItem.of(product, variantId, quantity);
        final Cart cartWithLineItem = client().executeBlocking(CartUpdateCommand.of(cart, updateAction));

        final LineItem lineItem = cartWithLineItem.getLineItems().get(0);
        assertThat(lineItem.getTaxRate()).isNull();
        assertThat(lineItem.getTotalPrice()).isEqualTo(EURO_30);
        assertThat(lineItem.getTaxedPrice()).isNull();

        //now add the taxes
        final String taxRateName = "special tax";
        final double taxRate = 0.20;
        final ExternalTaxRateDraft externalTaxRate =
                ExternalTaxRateDraftBuilder.ofAmount(taxRate, taxRateName, DE).includedInPrice(false).build();

        final SetLineItemTaxRate setLineItemTaxRate = SetLineItemTaxRate.of(lineItem.getId(), externalTaxRate);
        final Cart cartWithTaxedLineItem =
                client().executeBlocking(CartUpdateCommand.of(cartWithLineItem, setLineItemTaxRate));

        final LineItem taxedLineItem = cartWithTaxedLineItem.getLineItems().get(0);
        assertThat(taxedLineItem.getTaxRate().getName()).isEqualTo(taxRateName);
        assertThat(taxedLineItem.getTaxRate().isIncludedInPrice()).isEqualTo(false);
        assertThat(taxedLineItem.getTotalPrice()).isEqualTo(EURO_30);
        assertThat(taxedLineItem.getTaxedPrice().getTotalGross()).isEqualTo(EURO_36);
        assertThat(taxedLineItem.getTaxedPrice().getTotalNet()).isEqualTo(EURO_30);

        return cartWithTaxedLineItem;
    });
});
See the test code.

Add a CustomLineItem with an external tax rate

final CartDraft draft = CartDraft.of(EUR)
        .withTaxMode(TaxMode.EXTERNAL)
        .withShippingAddress(Address.of(DE));
withCartDraft(client(), draft, (Cart cart) -> {
    final MonetaryAmount money = MoneyImpl.of("23.50", EUR);
    final String slug = "thing-slug";
    final LocalizedString name = en("thing");
    final long quantity = 5;
    final String taxRateName = "special tax";
    final double taxRate = 0.20;
    final ExternalTaxRateDraft externalTaxRate =
            ExternalTaxRateDraftBuilder.ofAmount(taxRate, taxRateName, DE).build();
    final CustomLineItemDraft item = CustomLineItemDraft.ofExternalTaxCalculation(name, slug, money, externalTaxRate, quantity);

    final Cart cartWithCustomLineItems = client().executeBlocking(CartUpdateCommand.of(cart, AddCustomLineItem.of(item)));
    assertThat(cartWithCustomLineItems.getCustomLineItems()).hasSize(1);
    final CustomLineItem customLineItem = cartWithCustomLineItems.getCustomLineItems().get(0);

    assertThat(customLineItem.getTaxCategory()).isNull();
    assertThat(customLineItem.getTaxedPrice().getTotalNet()).isEqualTo(MoneyImpl.of("117.50", EUR));
    assertThat(customLineItem.getTaxedPrice().getTotalGross()).isEqualTo(MoneyImpl.of("141.00", EUR));
    assertThat(customLineItem.getTaxRate().getName()).isEqualTo(taxRateName);

    return cartWithCustomLineItems;
});
See the test code.

Add a CustomLineItem and add the external tax rate later

final CartDraft draft = CartDraft.of(EUR)
        .withTaxMode(TaxMode.EXTERNAL)
        .withShippingAddress(Address.of(DE));
withCartDraft(client(), draft, (Cart cart) -> {
    final MonetaryAmount money = MoneyImpl.of("23.50", EUR);
    final String slug = "thing-slug";
    final LocalizedString name = en("thing");
    final long quantity = 5;
    final CustomLineItemDraft item = CustomLineItemDraft.ofExternalTaxCalculation(name, slug, money, quantity);

    final Cart cartWithCustomLineItem = client().executeBlocking(CartUpdateCommand.of(cart, AddCustomLineItem.of(item)));
    assertThat(cartWithCustomLineItem.getCustomLineItems()).hasSize(1);
    final CustomLineItem customLineItem = cartWithCustomLineItem.getCustomLineItems().get(0);

    assertThat(customLineItem.getTaxCategory()).isNull();
    assertThat(customLineItem.getTaxedPrice()).isNull();
    assertThat(customLineItem.getTaxRate())
            .as("custom line item does not have tax information yet")
            .isNull();

    final String taxRateName = "special tax";
    final double taxRate = 0.20;
    final ExternalTaxRateDraft externalTaxRate =
            ExternalTaxRateDraftBuilder.ofAmount(taxRate, taxRateName, DE).build();

    final SetCustomLineItemTaxRate updateAction = SetCustomLineItemTaxRate.of(customLineItem.getId(), externalTaxRate);
    final Cart cartWithTaxedLineItem = client().executeBlocking(CartUpdateCommand.of(cartWithCustomLineItem, updateAction));

    final CustomLineItem taxedCustomLineItem = cartWithTaxedLineItem.getCustomLineItems().get(0);
    assertThat(taxedCustomLineItem.getTaxCategory()).isNull();
    assertThat(taxedCustomLineItem.getTaxedPrice().getTotalNet()).isEqualTo(MoneyImpl.of("117.50", EUR));
    assertThat(taxedCustomLineItem.getTaxedPrice().getTotalGross()).isEqualTo(MoneyImpl.of("141.00", EUR));
    assertThat(taxedCustomLineItem.getTaxRate().getName()).isEqualTo(taxRateName);

    return cartWithTaxedLineItem;
});
See the test code.

Add a custom shipping method with an external tax rate

final CartDraft draft = CartDraft.of(EUR)
        .withTaxMode(TaxMode.EXTERNAL)
        .withShippingAddress(Address.of(DE));
withCartDraft(client(), draft, (Cart cart) -> {
    final String taxRateName = "special tax";
    final double taxRate = 0.20;
    final ExternalTaxRateDraft externalTaxRate =
            ExternalTaxRateDraftBuilder.ofAmount(taxRate, taxRateName, DE).build();
    final ShippingRate shippingRate = ShippingRate.of(EURO_10,null, Collections.emptyList());
    final SetCustomShippingMethod action =
            SetCustomShippingMethod.ofExternalTaxCalculation("name", shippingRate, externalTaxRate);

    final Cart cartWithShippingMethod = client().executeBlocking(CartUpdateCommand.of(cart, action));

    final CartShippingInfo shippingInfo = cartWithShippingMethod.getShippingInfo();
    assertThat(shippingInfo).isNotNull();
    assertThat(shippingInfo.getShippingRate()).isEqualTo(shippingRate);
    assertThat(shippingInfo.getTaxCategory()).isNull();
    assertThat(shippingInfo.getTaxedPrice().getTotalNet()).isEqualTo(EURO_10);
    assertThat(shippingInfo.getTaxedPrice().getTotalGross()).isEqualTo(EURO_12);
    assertThat(shippingInfo.getTaxRate().getName()).isEqualTo(taxRateName);

    return cartWithShippingMethod;
});
See the test code.

Add a custom shipping method and add the external tax rate later

final CartDraft draft = CartDraft.of(EUR)
        .withTaxMode(TaxMode.EXTERNAL)
        .withShippingAddress(Address.of(DE));
withCartDraft(client(), draft, (Cart cart) -> {
    final ShippingRate shippingRate = ShippingRate.of(EURO_10,null, Collections.emptyList());
    final SetCustomShippingMethod action =
            SetCustomShippingMethod.ofExternalTaxCalculation("name", shippingRate);

    final Cart cartWithShippingMethod = client().executeBlocking(CartUpdateCommand.of(cart, action));

    final CartShippingInfo shippingInfo = cartWithShippingMethod.getShippingInfo();
    assertThat(shippingInfo).isNotNull();
    assertThat(shippingInfo.getShippingRate()).isEqualTo(shippingRate);
    assertThat(shippingInfo.getTaxCategory()).isNull();
    assertThat(shippingInfo.getTaxedPrice()).isNull();
    assertThat(shippingInfo.getTaxRate()).isNull();


    final String taxRateName = "special tax";
    final double taxRate = 0.20;
    final ExternalTaxRateDraft externalTaxRate =
            ExternalTaxRateDraftBuilder.ofAmount(taxRate, taxRateName, DE).build();

    final CartUpdateCommand cmd =
            CartUpdateCommand.of(cartWithShippingMethod, SetShippingMethodTaxRate.of(externalTaxRate));
    final Cart cartWithTaxedShippingMethod = client().executeBlocking(cmd);

    final CartShippingInfo taxedShippingInfo = cartWithTaxedShippingMethod.getShippingInfo();
    assertThat(taxedShippingInfo).isNotNull();
    assertThat(taxedShippingInfo.getShippingRate()).isEqualTo(shippingRate);
    assertThat(taxedShippingInfo.getTaxCategory()).isNull();
    assertThat(taxedShippingInfo.getTaxedPrice().getTotalNet()).isEqualTo(EURO_10);
    assertThat(taxedShippingInfo.getTaxedPrice().getTotalGross()).isEqualTo(EURO_12);
    assertThat(taxedShippingInfo.getTaxRate().getName()).isEqualTo(taxRateName);

    return cartWithTaxedShippingMethod;
});
See the test code.

Change the tax mode of a cart

Example

final CartDraftDsl cartDraft = CartDraft.of(EUR)
        .withTaxMode(TaxMode.EXTERNAL);//important

final Cart externalTaxModeCart = client().executeBlocking(CartCreateCommand.of(cartDraft));

assertThat(externalTaxModeCart.getTaxMode()).isEqualTo(TaxMode.EXTERNAL);

final Cart platformTaxModeCart =
        client().executeBlocking(CartUpdateCommand.of(externalTaxModeCart, ChangeTaxMode.of(TaxMode.PLATFORM)));

assertThat(platformTaxModeCart.getTaxMode()).isEqualTo(TaxMode.PLATFORM);
See the test code.

It fails if the products does not have a tax category set

withProductOfPrices(client(), singletonList(PriceDraft.of(EURO_10)), (Product product) -> {
    final CartDraft draft = CartDraft.of(EUR).withTaxMode(TaxMode.EXTERNAL);
    withCartDraft(client(), draft, (Cart cart) -> {
        final int quantity = 3;
        final int variantId = product.getMasterData().getStaged().getMasterVariant().getId();
        final String taxRateName = "special tax";
        final double rate = 0.20;
        final List<SubRate> subRates = asList(SubRate.of("foo", 0.11), SubRate.of("bar", 0.09));
        final ExternalTaxRateDraft externalTaxRate =
                ExternalTaxRateDraftBuilder.ofAmount(rate, taxRateName, DE)
                        .subRates(subRates)
                        .build();
        final AddLineItem updateAction = AddLineItem.of(product, variantId, quantity)
                .withExternalTaxRate(externalTaxRate);
        final Cart cartWithLineItem = client().executeBlocking(CartUpdateCommand.of(cart, updateAction));

        final LineItem lineItem = cartWithLineItem.getLineItems().get(0);
        final TaxRate taxRate = lineItem.getTaxRate();
        assertThat(taxRate.getName()).isEqualTo(taxRateName);

        final CartUpdateCommand setTaxModeCmd =
                CartUpdateCommand.of(cartWithLineItem, ChangeTaxMode.of(TaxMode.PLATFORM));
        final Throwable throwable = catchThrowable(() -> client().executeBlocking(setTaxModeCmd));

        assertThat(throwable)
                .as("it is not possible to change the cart to platform tax mode, " +
                        "if the product does not have a tax category")
                .isInstanceOf(ErrorResponseException.class);

        return cartWithLineItem;
    });
});
See the test code.

In case you use CustomLineItems as well as external and Composable Commerce tax mode, it is advised to add the tax category at the time of the creation of the custom line item if you don't know which tax mode will be used later. A cart with an external tax mode and a custom line item without a tax category cannot be transformed into a cart with 'Platform' mode tax calculation, to recover from this the custom object needs to be removed and added with a tax category.

EXTERNAL_AMOUNT

public static final TaxMode EXTERNAL_AMOUNT

The tax amounts and the tax rates as well as the tax portions are set externally per ExternalTaxAmountDraft. A cart with this tax mode can only be ordered if the cart itself and all line items, all custom line items and the shipping method have an external tax amount and rate set.

DISABLED

public static final TaxMode DISABLED

No taxes are added to the cart.

Method Detail

values

public static TaxMode[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (TaxMode c : TaxMode.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static TaxMode valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

ofSphereValue

public static TaxMode ofSphereValue(String value)