Relationship
objects have associated types. These types determine what happens when an Order
is checked out, as well as what types the relationship’s member variables have. This section describes the following Relationship
objects and their possible relationship types:
For details on assigning items to relationships of specific types, see the next two sections, Assigning Items to Shipping Groups and Assigning Costs to Payment Groups.
Note: For all of the following relationship types, quantities and amounts designated by a number are processed as “up to and including” the given number. For example, if a PaymentAmount
relationship exists with quantity 6 and references an item with quantity 10, 6 of those items will be paid for using the PaymentGroup
that the relationship references. The remaining 4 will be handled by the next relationship whose priority is less than the first relationship. On the other hand, if the relationship contained quantity 15, then all 10 items will be paid for using that first PaymentGroup
.
Also note that it is not possible to have more than one Relationship
of a specific “remaining” type (described below) in any given object. For example, a given CommerceItem
cannot have more than one PaymentGroupRelationship
of a remaining type. However, it can have a PaymentGroupRelationship
and a ShippingGroupRelationship
– both of a remaining type – because the two relationships are separate entities.
ShippingGroupCommerceItemRelationship Object
A ShippingGroupCommerceItemRelationship
represents a relationship between a CommerceItem
and a ShippingGroup
. This relationship can be assigned the relationship type ShippingQuantity
or ShippingQuantityRemaining
. These relationship types assign CommerceItems
to ShippingGroups
that specify which items in the Order
will be shipped to each destination. The following list describes the relationship types:
ShippingQuantity
: This relationship type indicates that a specific quantity of the item will be shipped using the information in theShippingGroup
. The quantity to ship is stored inside theRelationship
, and the quantity purchased is stored inside theCommerceItem
. If the quantity in theRelationship
is greater than the quantity in theCommerceItem
, then all theCommerceItems
are shipped to the location in theShippingGroup
.ShippingQuantityRemaining
: This relationship type indicates that the remaining quantity of the item unaccounted for by otherShippingGroupCommerceItemRelationship
objects will be shipped using the information in theShippingGroup
.Note: Any
ShippingQuantityRemaining
relationships have the lowest priority. ACommerceItem
can have only oneRelationship
of typeShippingQuantityRemaining
.
For example, a customer places an order for CommerceItem
Apple with quantity 10. Two ShippingGroups
already exist, SG1 (home) and SG2 (office).
The customer wants three apples shipped to his home, so a ShippingGroupCommerceItemRelationship
is created between CI1 (apple) and SG1 (home). This relationship type is ShippingQuantity
and the quantity to ship is 3.
The customer wants the remaining seven apples shipped to his office. A ShippingGroupCommerceItemRelationship
is created between CI1 (apple) and SG2 (office). This relationship can have either the relationship type ShippingQuantity
with quantity 7, or the relationship type ShippingQuantityRemaining
.
The difference between creating a second relationship with type ShippingQuantity
and using ShippingQuantityRemaining
is that, using ShippingQuantity
, if the quantity of CI1 increases, then the new items would not be assigned to a ShippingGroup
. If the second relationship is of type ShippingQuantityRemaining
, then the new items default to the ShippingGroup
in that relationship.
Both relationship types use an atg.core.util.Range
object to determine which particular CommerceItems
to include for a given quantity. Set the Range’s lowBound
and highBound
to indicate which items to include. Bounds are inclusive. For example, if one CommerceItemShippingGroupRelationship
accounts for four out of six CommerceItems
, setting the lowBound
to 1 and the highBound
to 4 means the first four CommerceItems
are shipped using this relationship. Setting the lowBound
to 3 and the highBound
to 6 means the last four are shipping using this relationship.
Range information is calculated when the end user checks out, ensuring correct pricing for each CommerceItem
regardless of any changes the user may make to ShippingGroups
while browsing.
PaymentGroupOrderRelationship Object
A PaymentGroupOrderRelationship
represents a relationship between an Order
and a PaymentGroup
. There are two ways to split the cost of an Order
across PaymentGroups
. Either split the entire cost by using PaymentGroupOrderRelationships,
or assign different types of costs (such as item cost vs. tax) to separate PaymentGroups
.
A PaymentGroupOrderRelationship
can be assigned the type OrderAmount
, OrderAmountRemaining
, TaxAmount
, or TaxAmountRemaining
. These relationship types assign the order and tax amounts to different PaymentGroups
. The following list describes the relationship types:
OrderAmount
: This relationship type indicates that a specific amount of the total cost of theOrder
(includingCommerceItems
,ShippingGroups
, and tax) will be paid using the information in thePaymentGroup
. The amount must be greater than zero. If the relationship amount is greater than the total amount of theOrder
, then the cost of the entireOrder
will be paid using the referencedPaymentGroup
.OrderAmountRemaining
: This relationship type indicates that the remaining cost of theOrder
unaccounted for by otherPaymentGroupOrderRelationship
objects will be paid using the information in thePaymentGroup
.Note: An
Order
can have only oneRelationship
of typeOrderAmountRemaining
.TaxAmount
: This relationship type indicates that a specific amount of the tax charged for theOrder
will be paid using the information in thePaymentGroup
. The amount must be greater than zero. If the relationship amount is greater than the total amount of theOrder
, then all the tax will be paid for using the referencedPaymentGroup
.TaxAmountRemaining
: This relationship type indicates that the tax cost unaccounted for by otherPaymentGroupOrderRelationship
objects will be paid using the information in the referencedPaymentGroup
.Note: An
Order
can have only oneRelationship
of typeTaxAmountRemaining
.
Example #1
The following example describes how to use the OrderAmount
and OrderAmountRemaining
types.
A customer places an Order
with a total of $600. The customer wants to pay for the order using two credit cards (Visa and MasterCard). A different PaymentGroup
represents each credit card. Two relationships are created to split the payment:
One
PaymentGroupOrderRelationship
is created between the Visa’sPaymentGroup
and theOrder
. The relationship type is set toOrderAmount
, and the amount is set to $400.One
PaymentGroupOrderRelationship
is created between the MasterCard’sPaymentGroup
and theOrder
. The relationship type is set toOrderAmountRemaining
.
When the Order
is charged, $400 will be charged on the Visa and $200 will be charged on the MasterCard.
Example # 2
The following example describes how to use the TaxAmountRemaining
type.
A customer places an order with a total tax of $100. The customer wants to pay for the tax with a separate credit card than the rest of the order payment. A PaymentGroupOrderRelationship
is created between the PaymentGroup
that represents the credit card and the Order
. The relationship type is set to TaxAmountRemaining,
which covers whatever the tax amount turns out to be.
PaymentGroupCommerceItemRelationship Object
A PaymentGroupCommerceItemRelationship
represents a relationship between a CommerceItem
and a PaymentGroup
. This relationship type is used to split payment for a single CommerceItem
between multiple payment groups.
The relationship can have the relationship type PaymentAmount
or PaymentAmountRemaining
. The following list describes the relationship types:
PaymentAmount
: This relationship type indicates that a specific amount of the item’s cost will be paid for using the information in thePaymentGroup
. The amount must be greater than zero. If the amount is greater than the total amount of the item stored in theCommerceItem
, then the entire cost of the item will be paid for using the referencedPaymentGroup
.PaymentAmountRemaining
: This relationship type indicates that any remaining payment amount unaccounted for by otherPaymentGroupCommerceItemRelationship
objects will be paid using the information in thePaymentGroup
. If there is only one relationship between a givenCommerceItem
and aPaymentGroup
of typePaymentAmountRemaining
, then the entire cost of that item will be paid for using the information in thePaymentGroup
.Note: A
CommerceItem
can have only oneRelationship
of typePaymentAmountRemaining
.
For example, a customer places an order for a CommerceItem
(Car) with the total cost $10,000. The customer wants to split the payment of this item between three credit cards (Visa, MasterCard, and American Express). A different PaymentGroup
represents each credit card. To split the item between three payment groups, PaymentGroupCommerceItemRelationships
must be created between the CommerceItem
(Car) and the three PaymentGroup
objects:
The first
PaymentGroupCommerceItemRelationship
connects theCommerceItem
(car) and the firstPaymentGroup
(Visa). The relationship type is set toPaymentAmount
, and the amount is set to $4000.The second
PaymentGroupCommerceItemRelationship
connects theCommerceItem
(car) and the secondPaymentGroup
(MasterCard). The relationship type is set toPaymentAmount
, and the amount is set to $4000.The third
PaymentGroupCommerceItemRelationship
connects theCommerceItem
(car) and the thirdPaymentGroup
(American Express). The relationship type is set toPaymentAmountRemaining
.
PaymentGroupShippingGroupRelationship Object
A PaymentGroupShippingGroupRelationship
represents a relationship between a ShippingGroup
and a PaymentGroup
. This type of Relationship
is used to assign shipping costs in a ShippingGroup
to PaymentGroups.
This relationship can be assigned the relationship types ShippingAmount
or ShippingAmountRemaining
. The following list describes the relationship types:
ShippingAmount
: This relationship type indicates that a specific amount of the shipping cost will be paid using the information in thePaymentGroup
. The amount must be greater than zero. If the amount is greater than the total amount of the item stored in theShippingGroup
, then the cost of the entire item will be paid using the referencedPaymentGroup
.ShippingAmountRemaining
: This relationship type indicates that any remaining shipping cost amount unaccounted for by otherPaymentGroupShippingGroupRelationship
objects will be paid using the information in thePaymentGroup
. If there is only one relationship between a givenShippingGroup
and aPaymentGroup
of typePaymentAmountRemaining
, then the entire shipping cost will be paid using the information in thePaymentGroup
.Note: A
ShippingGroup
can have only oneRelationship
of typePaymentAmountRemaining
.
For example, an order is shipped to one location stored in a ShippingGroup
. The shipping costs are $10. The customer wants to pay for the shipping costs with a credit card. The credit card information is stored in the only PaymentGroup
. A PaymentGroupShippingGroupRelationship
of type ShippingAmount
is created, and the amount is set to $10.