TABLE OF CONTENTS
- B2C Shopping Cart
- Shopping Cart Object
- Shopping Cart Item Object
- Shopping Cart Combo Item Object
- Donation Details Object
- Sample Request Bodies
- Sample Responses
B2C Shopping Cart
Shopping carts help you collect and manage items users select as they navigate through the purchase flows. The cart can either be built and updated as a stand-alone object or it can be built directly in the checkout call when the order is submitted.
Note: Creating a stand-alone shopping cart isn’t required for checkout but the shopping cart object is used in most of the checkout flows. For that reason, we strongly recommend using the shopping cart features.
Method | Endpoint | Actions | Request Payload | Response Payload |
POST | /v2/b2c/carts | Create a new shopping cart | Shopping Cart Object* | Shopping Cart ID |
GET | /v2/b2c/carts/{id} | Get an existing shopping cart | None | Shopping Cart Object |
PUT | /v2/b2c/carts/{id} | Update an existing shopping cart | Shopping Cart Object | Shopping Cart Object |
DELETE | /v2/b2c/carts/{id} | Delete an existing shopping cart | None | Shopping Cart Object |
*If you’d like to create an empty shopping cart, pass an empty object {} into the create a new shopping cart call
Shopping Cart Object
| Field | Description | Notes |
|---|---|---|
| id | If it's an existing shopping cart then the id of the cart. | |
| tempVisitorId | ACME internal use only. Use customerId below. | |
| visitorId | ACME internal use only. Use customerId below. | |
| membershipId | ACME internal use only. Use membershipIds below. | |
| membershipCategoryId | The ID of the level. If you don't have the membership id but know the membership level then you can pass this in to give them membership discounts and access. If you pass in a membership id then this will not be used. | |
| couponCode | ACME internal use only. Use couponCodes below. Populating this field will cause the coupons to not be applied to the cart. | |
| items | A list of items in the shopping cart. See Shopping Cart Item Object for details. | Required |
| comboItems | A list of combo items in the cart. This is for a combo event not combo ticket category. See Shopping Cart Combo Item Object for details. | |
| forms | ACME internal use only. | |
| couponCodes | A list of coupon codes being applied to this cart. | |
| customerId | The id of an existing customer. A new customer can be created during B2C Checkout. | |
| membershipIds | A list of membership IDs that are being used on the order | |
| orderContact | ACME internal use only. | |
| saleChannel | The sales channel that this order was completed on. one of (online, customerRep, pointOfSale, reseller, kiosk or collaborator) | Required |
| org | ACME internal use only |
Shopping Cart Item Object
| Field | Description | Notes |
|---|---|---|
| itemId | A unique id for this item | Read Only |
| eventId | Event id of the item | Required for Events |
| ticketingTypeId | Type of ticket | Required for Events |
| eventName | The name of the event | Read Only |
| ticketTypeName | The name of the ticket type | Read Only |
| quantity | The number of these items in the shopping cart | Required |
| unitPrice | The price for each item in the shopping cart | Read Only |
| amount | The total amount (quantity * unitPrice). Used only for variable donation prices. | Read Only |
| itemType | The type of item. Can be one of Event, Inventory, ComboEvent, ComboInventory. The default is Event. | Required |
| inventoryId | If this item is not an event then this is the inventory id of the item. | Required for Add On or Donation |
| inventoryName | Name of the item, if it's not an event. | Read Only |
| membershipInfo | Information about the membership being purchased. See Membership Info Object | |
| discountId | If a discount is applicable (i.e. if you are using a coupon code), the discount id will be returned | Read Only |
| donationDetail | The details about the donation if this item is a donation. See Donation Details Object below | Optional |
| ignoreEntitlements | If a membership is being used to make this purchase then setting this flag will ignore restrictions on the membership. Like Gold members can only buy two tickets will be ignored and the member will be able to buy more. |
Shopping Cart Combo Item Object
| Field | Description |
|---|---|
| itemId | The inventory item id, if this is an inventory item. |
| comboTemplateId | The combo template id associated with this combo item. |
| comboTemplateName | the name of the combo template. |
| comboTemplateType | Either fixedPrice or Discount depending on the type combo template. |
| tickets | The list of tickets for this combo item. |
| tickets[x].eventTemplateId | The event template associated with this ticket. |
| tickets[x].ticketTypeId | The id for the type of ticket. |
| tickets[x].name | The name on the ticket. |
| tickets[x].description | A description of what the ticket is for. |
| tickets[x].price | The retail price of the ticket. |
| tickets[x].discountedPrice | The price after discounts for resellers are applied to the retail price. |
| tickets[x].quantity | The number of tickets. |
| tickets[x].subTotal | The subtotal of the retail price of the tickets for the purchased quantity |
| tickets[x].discountedSubTotal | The subtotal of the discounted price of the tickets for the purchased quantity |
| events | A list of events in this combo. |
| events[x].eventTemplateId | The id of the event template for this event. |
| events[x].eventId | The id of the event. |
| events[x].eventName | The name of the event. |
| events[x].eventStartTime | The start time of the event. |
| addOns | The list of add ons in this combo item. |
| addOns[x].addOnId | The id of the add-on . |
| addOns[x].name | The name of the add on. |
| addOns[x].quantity | The number of items of this add on in the shopping cart. |
| addOns[x].unitPrice | The price of these items. |
| addOns[x].priceSplit | Either 'each' or 'total'. If each then the price will be quantity * unitPrice, if total the price will be unitPrice. |
Donation Details Object
Information about the donation being made
| Field | Description | Notes |
|---|---|---|
| donorRecognition | 'self', 'anonymous' or the name of the organization | This maps to "DonorRecognitionCorpName" in reporting. If donor recognition type is
|
| donorRecognitionTag | The recognition notes | |
| donorRecognitionType | Whether the donation is a 'self', 'organization', or 'anonymous' donation | Required. If 'self', customer (donor) information is pulled from checkout billing information |
| dedicationLastName | Last name of the person that is being honored in beneficiary type | |
| dedicationFirstName | First name of the person that is being honored in beneficiary type | |
| donationCampaignName | Name of the campaign that the donation is for | Campaigns are created in ACME B2B. Use Get Campaigns to get the available list. |
| donationAppealName | Appeal that the donation is for | Appeals are created in ACME B2B. Use Get Appeals to get the available list. |
| donationFundName | Fund that the donation is for | Funds are created in ACME B2B. Use Get Funds to get the available list. |
| beneficiaryType | 'In honor of' or 'In memory of' | |
| beneficiaryLastName | last name of the person being informed | |
| beneficiaryFirstName | first name of the person being informed | |
| beneficiaryEmail | email of the person being informed | |
| beneficiaryPhoneNumber | phone number of the person being informed | |
| beneficiaryStreetAddress1 | street address 1 of the person being informed | |
| beneficiaryStreetAddress2 | street address 2 of the person being informed | |
| beneficiaryCity | city of the person being informed | |
| beneficiaryState | state of the person being informed | |
| beneficiaryZip | zip code of the person being informed | |
| beneficiaryCountry | country of the person being informed | |
| notes | 'in honor of' or 'in memory of' notes | |
| customFieldValues | A list of name value pairs associated with this donation | |
| customFieldValues[x].name | ||
| customFieldValues[x].value |
Sample Request Bodies
Create a new shopping cart or update an existing shopping cart. This example includes all possible items that can be included in a cart. Add or remove items depending on what the user selects.
//Event Example
{
"items": [{
"itemType": "Event",
"eventName": "History of Magic",
"eventId": "5d96453460309f26d082bc80",
"ticketingTypeName": "Adult",
"ticketingTypeId": "55268c54e4b0fb9be01106bd",
"quantity": 2,
"unitPrice": "20.00",
"amount": "40.00"
},
//Event Add-On Example
{
"itemType": "Inventory",
"eventName": "History of Magic",
"eventId": "5d96453460309f26d082bc80",
"inventoryName": "Horocrux",
"inventoryId": 594,
"quantity": 1,
"unitPrice": "100.00",
"amount": "100.00"
},
//Discrete Add-On Example (does not have an event attached)
{
"itemType": "Inventory",
"inventoryName": "Floo Powder",
"inventoryId": 818,
"quantity": 1,
"unitPrice": "10.00",
"amount": "10.00"
},
//Fixed Donation Example
{
"itemType": "Inventory",
"addonType": "fixedDonation",
"inventoryName": "$10 Donation",
"inventoryId": 889,
"quantity": 1,
"unitPrice": "100.00",
"amount": "100.00",
"donationDetail": {
"donationAppealName": "Appeal One",
"donationCampaignName": "Spring Direct Mail Appeal",
"donationFundName": "General Fund",
"donorRecognition": "self",
"donorRecognitionType": "self",
"dedicationLastName": "Longbottom",
"dedicationFirstName": "Mr. and Mrs.",
"beneficiaryType": "In memory of",
"beneficiaryLastName": "Longbottom",
"beneficiaryFirstName": "Neville",
"beneficiaryEmail": "nlongbottom@hsww.magic.edu",
"beneficiaryPhoneNumber": "555-555-5555",
"beneficiaryStreetAddress1": "123 Main Street",
"beneficiaryStreetAddress2": "Apt 2B",
"beneficiaryCity": "Anytown",
"beneficiaryState": "GA",
"beneficiaryZipCode": "30303",
"beneficiaryCountry": "United States"
}
},
//Variable Donation Example
{
"itemType": "Inventory",
"addonType": "donation",
"inventoryName": "Variable Donation",
"inventoryId": 888,
"quantity": 1,
"unitPrice": "10000.00",
"amount": "10000.00",
"donationDetail": {
"donationAppealName": "Appeal One",
"donationCampaignName": "Spring Direct Mail Appeal",
"donationFundName": "General Fund",
"donorRecognition": "anonymous",
"donorRecognitionType": "anonymous"
}
},
//Membership Purchase Example (new membership only)
{
"itemType": "MembershipPurchase",
"quantity": 1,
"unitPrice": "100.00",
"amount": "100.00",
"membershipInfo": {
"membershipCategoryId": "5a049c3b60309f5d917c6e63",
"membershipCategoryName": "Founders",
"membershipOfferingId": "519d569cd32748ae9e3c507fe0456e5e",
"membershipOfferingName": "Offering One",
"pricePointId": "59aeb29a60309f07f6c6bef6",
"pricePointName": "Membership",
"membershipCards": [{
"cardType": "primary",
"name": "B Bagshot",
"email": "bbagshot@email.com",
"firstName": "B",
"lastName": "Bagshot",
"phoneNumber": "555-555-5555",
"streetAddress1": "123 Main St",
"streetAddress2": "Apt 2",
"city": "Springfield",
"state": "Oregon",
"zipCode": "97477",
"country": "United States"
},
{
"cardType": "secondary",
"email": "hsimpson@springfieldnuclear.org",
"firstName": "H",
"lastName": "Simpson",
"phoneNumber": "939-555-0113"
}
],
"isGift": false
}
}
],
"forms": [],
"comboItems": [],
"verifyEntitlements": false,
"reservationId": "10788"
}Sample Responses
Empty shopping cart object
{
"id": "5e14cd4f60309f41499e653b",
"tempVisitorId": "706ae7924a824d2483ac8827db78511e",
"items": [],
"forms": [],
"comboItems": [],
"verifyEntitlements": false
}
Full shopping cart object
***coupon code and membership id cannot be used at the same time
{
"id": "5e173d6060309f41499e6602",
"tempVisitorId": "43b66f951401416781903934f8c68e9a",
"membershipCategoryId": "5a049c3b60309f5d917c6e63",
"membershipId": "000000000***",
"couponCodes" : ["CouponCode***"],
"items": [
{
// typical ticket example
"itemId": "fb433e2a72594339bfe1be054440cd41",
"eventId": "5d96453460309f26d082bc80",
"ticketingTypeId": "55268c54e4b0fb9be01106bd",
"eventName": "History of Magic",
"ticketingTypeName": "Adult",
"quantity": 2,
"unitPrice": "20.00",
"retailUnitPrice": "20.00",
"amount": "40.00",
"itemType": "Event",
"admissionType": "standard",
"isRetail": false,
"ignoreEntitlements": false
},
{
// full price ticket when using entitlements example
"itemId": "fb433e2a72594339bfe1be054440cd41",
"eventId": "5d96453460309f26d082bc80",
"ticketingTypeId": "55268c54e4b0fb9be01106bd",
"eventName": "History of Magic",
"ticketingTypeName": "Adult",
"quantity": 2,
"unitPrice": "20.00",
"retailUnitPrice": "20.00",
"amount": "40.00",
"itemType": "Event",
"admissionType": "standard",
"isRetail": true,
"ignoreEntitlements": false
},
{
// addon tied to event example
"itemId": "0b2dc945b9e34bd2ab3c1ff8fb407d7b",
"eventId": "5d96453460309f26d082bc80",
"eventName": "History of Magic",
"quantity": 1,
"unitPrice": "100.00",
"retailUnitPrice": "0.00",
"amount": "100.00",
"itemType": "Inventory",
"inventoryId": 594,
"inventoryName": "Horocrux",
"admissionType": "standard",
"isRetail": false,
"ignoreEntitlements": false
},
{
// addon not tied to an event example
"itemId": "b898f7f493834dab8d21946838a89b4f",
"quantity": 1,
"unitPrice": "10.00",
"retailUnitPrice": "0.00",
"amount": "10.00",
"itemType": "Inventory",
"inventoryId": 818,
"inventoryName": "Floo Powder",
"admissionType": "standard",
"isRetail": false,
"ignoreEntitlements": false
},
{
// fixed donation example
"itemId": "75df1d03e1534e37bbcefd6b956aaa2e",
"quantity": 1,
"unitPrice": "100.00",
"retailUnitPrice": "0.00",
"amount": "100.00",
"itemType": "Inventory",
"inventoryId": 889,
"inventoryName": "$10 Donation",
"admissionType": "standard",
"addonType": "fixedDonation",
"donationDetail": {
"donorRecognition": "self",
"donorRecognitionType": "self",
"dedicationLastName": "Longbottom",
"dedicationFirstName": "Mr. and Mrs.",
"donationCampaignName": "Spring Direct Mail Appeal",
"donationFundName": "General Fund",
"beneficiaryType": "In memory of",
"beneficiaryLastName": "Longbottom",
"beneficiaryFirstName": "Neville",
"beneficiaryEmail": "nlongbottom@hsww.magic.edu",
"beneficiaryPhoneNumber": "555-555-5555",
"beneficiaryStreetAddress1": "123 Main Street",
"beneficiaryStreetAddress2": "Apt 2B",
"beneficiaryCity": "Anytown",
"beneficiaryState": "GA",
"beneficiaryZipCode": "30303",
"beneficiaryCountry": "United States",
"customFieldValues": [],
"donationAppealName": "Appeal One"
},
"isRetail": false,
"ignoreEntitlements": false
},
{
// variable donation example
"itemId": "d52ab9a933e64b0bb82771cfeb1a871d",
"quantity": 1,
"unitPrice": "10000.00",
"retailUnitPrice": "0.00",
"amount": "10000.00",
"itemType": "Inventory",
"inventoryId": 888,
"inventoryName": "Variable Donation",
"admissionType": "standard",
"addonType": "donation",
"donationDetail": {
"donorRecognition": "anonymous",
"donorRecognitionType": "anonymous",
"donationCampaignName": "Spring Direct Mail Appeal",
"donationFundName": "General Fund",
"customFieldValues": [],
"donationAppealName": "Appeal One"
},
"isRetail": false,
"ignoreEntitlements": false
},
{
// membership purchase example
"itemId": "b278c0577a8a42d497dbaeca8bc7112a",
"quantity": 1,
"unitPrice": "100.00",
"retailUnitPrice": "100.00",
"amount": "100.00",
"itemType": "MembershipPurchase",
"membershipInfo": {
"membershipCategoryId": "5a049c3b60309f5d917c6e63",
"membershipCategoryName": "Founders",
"membershipOfferingId": "519d569cd32748ae9e3c507fe0456e5e",
"membershipOfferingName": "Offering One",
"pricePointId": "59aeb29a60309f07f6c6bef6",
"pricePointName": "Membership",
"membershipCards": [
{
"cardType": "primary",
"name": "B Bagshot",
"email": "bbagshot@email.com",
"firstName": "B",
"lastName": "Bagshot",
"phoneNumber": "555-555-5555",
"streetAddress1": "123 Main St",
"streetAddress2": "Apt 2",
"city": "Springfield",
"state": "Oregon",
"zipCode": "97477",
"country": "United States",
"deceased": "no",
"primaryCard": "no",
"startDate": "1969-12-31T19:00:01-05:00",
"expirationDate": "2038-01-18T22:14:07-05:00",
"excludeCardOnMemberCreation": false,
"ignoreUpdates": false
},
{
"cardType": "secondary",
"name": "H Simpson",
"email": "hsimpson@springfieldnuclear.org",
"firstName": "H",
"lastName": "Simpson",
"phoneNumber": "939-555-0113",
"deceased": "no",
"primaryCard": "no",
"startDate": "1969-12-31T19:00:01-05:00",
"expirationDate": "2038-01-18T22:14:07-05:00",
"excludeCardOnMemberCreation": false,
"ignoreUpdates": false
}
],
"waiveBenefits": false,
"isGift": false,
"notifyGiftRecipient": false,
"donationAmount": "0.00",
"markDonationAsAnonymous": false,
"cancellationRefundAmount": "0.00",
"auxiliary": false
},
"admissionType": "standard",
"isRetail": false,
"ignoreEntitlements": false
}
],
"forms": [],
"comboItems": [],
"verifyEntitlements": false
}