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:

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:

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:

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:

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:

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:

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.