Introduction

The ACME Shopping Cart is a collection of structured items that can be purchased, including Event Tickets, Add-ons, Memberships, and Donations. 


The power of the ACME Shopping cart is that these can all be purchased together in a unified cart. For example, if a guest purchases a Membership along with Event Tickets, the combination in a single shopping cart allows you to provide immediate membership benefits, such as discounts on the tickets.


Header Parameters
B2C endpoints have required headers for all calls. See Header Parameters for more detail. 

For response codes, see API Response Codes and Error Messages

Endpoints

For each endpoint below, we provide a brief overview of what it does, the required and optional parameters, as well as an example request and response.



Create a New Shopping CartPOST /v2/b2c/carts
Get a Shopping CartGET /v2/b2c/carts/{id}
Update a Shopping CartPUT /v2/b2c/carts/{id}


Additional Examples

Create a New Shopping Cart


POST /v2/b2c/carts


Description

The ACME Shopping Cart helps you collect and manage items users select as they navigate through the purchase flows.  


Things to note: 


Required Parameters

Note: These are only required if you want to add items upon creation. To create an empty shopping cart, pass an empty object {} in the request body.


items[ ] (Required)
A list of items in the shopping cart.
eventId  (Required for Events)
ID of the Event		Example:
61f99cfb62bd1f467c397829
ticketingTypeId  (Required for Events)
ID of the ticket type		Example:
6130fea5bf4aec4ef5db0dc5
quantity (Required)
The number of these items in the shopping cart		Example:
2


Optional Parameters

If you want to include optional parameters, or want to include items other than Events, see Shopping Cart Object.


Example - Create a New Shopping Cart

Request

curl --location --request POST 'https://sandX-api.acmeticketing.net/v2/b2c/carts' \
--header 'x-b2c-tenant-id: 123' \
--header 'x-acme-browser-ip: 255.255.255.255' \
--header 'x-acme-api-key: a4c5cfd307834890a6e1e09eb9e11b4d' \
--header 'Content-Type: application/json' \
--data '{
  "items": [{
        "eventId": "61f99cfb62bd1f467c397829",
        "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5",
        "quantity": 2
  }]
}'


Response

Returns the generated Shopping Cart ID.

643f4a219f0baf41144ce27d


Get a Shopping Cart


GET /v2/b2c/carts/{id}

Description

Get the details of the items present in an existing Shopping Cart.


Example

Request

curl --location --request GET 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643f4a219f0baf41144ce27d' \
--header 'x-b2c-tenant-id: 123' \
--header 'x-acme-browser-ip: 255.255.255.255' \
--header 'x-acme-api-key: a4c5cfd307834890a6e1e09eb9e11b4d' \

Response

Returns the Shopping Cart Object, which includes an array of the items in the cart.

{
    "id": "643f4a219f0baf41144ce27d",
    "tempVisitorId": "132a1ba1fc254449b6ecfe6f26a95397",
    "items": [
        {
            "itemId": "6a603a8c6f14457dbcb3869a6775ac64",
            "eventId": "61f99cfb62bd1f467c397829",
            "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5",
            "eventName": "Behind-the-Scenes Tour",
            "ticketingTypeName": "Adult",
            "quantity": 2,
            "unitPrice": "32.00",
            "retailUnitPrice": "32.00",
            "amount": "64.00",
            "itemType": "Event",
            "admissionType": "standard",
            "isRetail": false,
            "ignoreEntitlements": false
        }
    ],
    "forms": [],
    "comboItems": [],
    "verifyEntitlements": false
}

Update a Shopping Cart


PUT /v2/b2c/carts/{id}


Description

Use this endpoint when you want to update the contents of the shopping cart, such as the quantity or type of items present. 


Things to note: 


Required Parameters


id (Required)
ID of the Shopping Cart		Example:
61f99cfb62bd1f467c397829
items[ ] (Required)

A list of items in the shopping cart.  See Shopping Cart Item Object for details

items[x].eventId(Required for Events)
The ID of the event		Example:
61f99cfb62bd1f467c397829
items[x].ticketingTypeId (Required for Events)
ID of the ticket type		Example:
6130fea5bf4aec4ef5db0dc5
items[x].quantity: (Required for all)
The number of these items in the shopping cart		Example:
3

Quantity for Memberships and Donations is always '1'
items[x].inventoryId: (Required for Add-Ons and Donations)
ID of the Add-On or Donation

items[x].itemType: (Required for Add-Ons, Donations, and Memberships)
The Type of the Item
For Add-Ons and Donations it is 'Inventory'
For Membership Types, reference this article

items[x].type: (Required for Donations)
The Donation Type
Either 'fixedDonation' or 'donation' (if the item is a variable donation where the user can input their own desired amount)
items[x].membershipCategoryId: (Required for Memberships)
The ID of the Membership Level/Category

items[x].membershipOfferingId: (Required for Memberships)
The ID of the Membership Offering

items[x].pricePointId: (Required for Memberships)
The ID of the price point of the Membership

items[x].membershipInfo.membershipCards.firstName: (Required for Memberships)
The First Name of the Member
items[x].membershipInfo.membershipCards.lastName: (Required for Memberships)
The Last Name of the Member

items[x].membershipInfo.membershipCards.email
items[x].membershipInfo.membershipCards.phoneNumber
items[x].membershipInfo.membershipCards. address fields
: (Required for Memberships)

At least 1 of email, phone, or address is required to create a customer. This is required for primary cardholders and optional for secondary cardholders.


Optional Parameters

If you want to include optional parameters see Shopping Cart Object.


Example - Update a Shopping Cart

Request

curl --location --request PUT 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643f4a219f0baf41144ce27d' \
--header 'x-b2c-tenant-id: 123' \
--header 'x-acme-browser-ip: 255.255.255.255' \
--header 'x-acme-api-key: a4c5cfd307834890a6e1e09eb9e11b4d' \
--header 'Content-Type: application/json' \
--data-raw '{
	"id": "643f4a219f0baf41144ce27d",
         "items": [{
               "eventId": "61f99cfb62bd1f467c397829",
               "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5",
               "quantity": 3
         }]
}'


Response 

Returns the Shopping Cart Object

{
    "id": "643f4a219f0baf41144ce27d",
    "items": [
        {
            "itemId": "5c179c4927fb4b44b4fac91d5c63c365",
            "eventId": "61f99cfb62bd1f467c397829",
            "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5",
            "eventName": "Behind-the-Scenes Tour",
            "ticketingTypeName": "Adult",
            "quantity": 3,
            "unitPrice": "32.00",
            "retailUnitPrice": "32.00",
            "amount": "96.00",
            "itemType": "Event",
            "admissionType": "standard",
            "isRetail": false,
            "ignoreEntitlements": false
        }
    ],
    "forms": [],
    "comboItems": [],
    "verifyEntitlements": false
}


Additional Examples

Create a Shopping Cart with a Donation

In ACME, Donations are considered Inventory / Add Ons. There are two possible types:

  • Fixed Donation: Enables the donor to easily select from pre-configired amounts
  • Variable Donation: Enables the donor to type in any amount to donate


If desired, you can collect additional details from the donor and submit these as donationDetail. See Donation Detail Object (documentation coming soon) for more information.


And overall, learn more about donations with Donation Configuration ›


Example Request

curl --location 'https://sandX-api.acmeticketing.net/v2/b2c/carts' \
--header 'x-b2c-tenant-id: 123' \
--header 'x-acme-browser-ip: 255.255.255.255' \
--header 'x-acme-api-key: a4c5cfd307834890a6e1e09eb9e11b4d' \
--header 'Content-Type: application/json' \
--data-raw '{
    "items": [
        {
            "itemType": "Inventory",
            "addonType": "fixedDonation",
            "inventoryName": "$50",
            "inventoryId": 4575,
            "quantity": 1,
            "unitPrice": "50.00",
            "amount": "50.00",
            "donationDetail": {
                "donationAppealName": "Appeal One",
                "donationCampaignName": "Spring Direct Mail Appeal",
                "donationFundName": "General Fund",
                "donorRecognition": "self",
                "donorRecognitionType": "self",
                "dedicationLastName": "Doe",
                "dedicationFirstName": "Jane",
                "beneficiaryType": "In memory of",
                "beneficiaryLastName": "Doe",
                "beneficiaryFirstName": "John",
                "beneficiaryEmail": "johnDoe@gmail.com",
                "beneficiaryPhoneNumber": "555-555-5555",
                "beneficiaryStreetAddress1": "123 Main Street",
                "beneficiaryStreetAddress2": "Apt 2B",
                "beneficiaryCity": "Anytown",
                "beneficiaryState": "GA",
                "beneficiaryZipCode": "30303",
                "beneficiaryCountry": "United States"
            }
        }
    ]
}'


Example Response 

Returns the Shopping Cart ID

641b51a34649955db8ed9749


Create a Shopping Cart with an Add On

To sell an Event Add On, there must be one item for the Event Tickets and then there is a separate item for the Add On. The Add On is noted as an Event Add On by the "eventId" field, which is the Event ID as the event the Add On is tied to.


Fields required to add an Add-On:

1. inventoryId

2. itemType ('Inventory')

3. quantity

{
    "id": "5e173d6060309f41499e6602",
    "tempVisitorId": "43b66f951401416781903934f8c68e9a",
    "items": [
        {
            // This holds the information about the Event Tickets
            "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
        },
        {
            // This holds the information for the Add On that is tied to the Event
            "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,
        }
    ],
}


Create a Shopping Cart with a Form

If there are multiple events in the cart that each have a form and:

  • If they reference different forms, then each form will be shown to the user and will be tied to the event it is associated with.

  • If they reference the same form, then we look at the setting on the form that says to show "once per cart" true/false

    • If true: then the form will only be shown once but a form response is created for each event and that form response is saved to each event it is associated with

    • If false: then the form will be shown for each event and the form response will be saved for the event it is associated with


One Event with a Form 

{
    "id": "5e173d6060309f41499e6602",
    "tempVisitorId": "43b66f951401416781903934f8c68e9a",
    "items": [
        {
            "itemId": "6594494cfd0f3e13c4968b43",
            "eventId": "5d96453460309f26d082bc80",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "Admissions",
            "ticketingTypeName": "Adult",
            "quantity": 2,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "40.00",
            "itemType": "Event",
            "admissionType": "standard"
        }
    ],
    "forms": [
        {
           "formId": "6435cdd41be34d4cf366d1d4",
           "formResponseId": "661d653830570b6212dc5fa6",
            "itemId": "6594494cfd0f3e13c4968b43",
            "itemName": "Admissions",
            "itemType": "Event",
            "oncePerCart": true
        }
    ],
}


Multiple Events with different Forms configured


{
    "id": "5e173d6060309f41499e6602",
    "tempVisitorId": "43b66f951401416781903934f8c68e9a",
    "items": [
        {
            "itemId": "6594494cfd0f3e13c4968b3b",
            "eventId": "5ec3184fe8827e0ed34fbca0",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "Admissions",
            "ticketingTypeName": "Adult",
            "quantity": 1,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "20.00",
            "itemType": "Event",
            "admissionType": "standard"
        },
       {
            "itemId": "64d36cd94b501c7be374422a",
            "eventId": "5ec31bd0d2302445a258962d",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "School Tour",
            "ticketingTypeName": "Adult",
            "quantity": 1,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "20.00",
            "itemType": "Event",
            "admissionType": "standard"
        }
    ],
    "forms": [
        {
            formId: "6435cdd41be34d4cf366d1d4",
            formResponseId: "661d6f9e30570b6212dc5fb3",
            itemId: "6594494cfd0f3e13c4968b3b",
            itemName: "Admissions",
            itemType: "Event",
            oncePerCart: true
        },
       {
            formId: "64e7d2a07f5de041ce0cf7c9",
            formResponseId: "661d6fc330570b6212dc5fb4",
            itemId: "64d36cd94b501c7be374422a",
            itemName: "School Tour",
            itemType: "Event",
            oncePerCart: false
        }
    ],
}


Multiple Events with same Form configured to show "Once Per Cart"


{
    "id": "5e173d6060309f41499e6602",
    "tempVisitorId": "43b66f951401416781903934f8c68e9a",
    "items": [
        {
            "itemId": "6594494cfd0f3e13c4968b43",
            "eventId": "5ec3184fe8827e0ed34fbca0",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "Admissions",
            "ticketingTypeName": "Adult",
            "quantity": 2,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "40.00",
            "itemType": "Event",
            "admissionType": "standard"
        },
       {
            "itemId": "65e087aa84b3b952bad828db",
            "eventId": "56fab8a868d6097d2a7f4740",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "Sailing Lessons",
            "ticketingTypeName": "Adult",
            "quantity": 1,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "20.00",
            "itemType": "Event",
            "admissionType": "standard"
        }
    ],
    "forms": [
        {
            "formId": "6435cdd41be34d4cf366d1d4",
            "formResponseId": "661d653830570b6212dc5fa6",
            "itemId": "6594494cfd0f3e13c4968b43",
            "itemName": "Admissions",
            "itemType": "Event",
            "oncePerCart": true
        },
       {
            "formId": "6435cdd41be34d4cf366d1d4",
            "formResponseId": "661d653830570b6212dc5fa7",
            "itemId": "65e087aa84b3b952bad828db",
            "itemName": "Sailing Lessons",
            "itemType": "Event",
            "oncePerCart": true
        }
    ],
}


Multiple Events with same form configured to show "Once Per Event"


{
    "id": "5e173d6060309f41499e6602",
    "tempVisitorId": "43b66f951401416781903934f8c68e9a",
    "items": [
        {
            "itemId": "6594494cfd0f3e13c4968b43",
            "eventId": "5ec3184fe8827e0ed34fbca0",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "Admissions",
            "ticketingTypeName": "Adult",
            "quantity": 2,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "40.00",
            "itemType": "Event",
            "admissionType": "standard"
        },
       {
            "itemId": "65e087aa84b3b952bad828db",
            "eventId": "56fab8a868d6097d2a7f4740",
            "ticketingTypeId": "55268c54e4b0fb9be01106bd",
            "eventName": "Sailing Lessons",
            "ticketingTypeName": "Adult",
            "quantity": 1,
            "unitPrice": "20.00",
            "retailUnitPrice": "20.00",
            "amount": "20.00",
            "itemType": "Event",
            "admissionType": "standard"
        }
    ],
    "forms": [
        {
            "formId": "6435cdd41be34d4cf366d1d4",
            "formResponseId": "661d653830570b6212dc5fa6",
            "itemId": "6594494cfd0f3e13c4968b43",
            "itemName": "Admissions",
            "itemType": "Event",
            "oncePerCart": false
        },
       {
            formId: "6435cdd41be34d4cf366d1d4",
            formResponseId: "661d653830570b6212dc5fa7",
            itemId: "65e087aa84b3b952bad828db",
            itemName: "Sailing Lessons",
            itemType: "Event",
            oncePerCart: false
        }
    ],
}

Update a Shopping Cart with an Applied Coupon

PUT /v2/b2c/carts/{id}

You have the ability to apply coupons to both event tickets and memberships in the cart. Valid coupon codes will apply the configured discount to the eligible items in the cart.


Things of note:

  • If the cart includes both a membership purchase and event tickets, by default a coupon will automatically be applied only to the purchase of the membership, as any event discounts will come from the membership.
  • If you would like to change the ticket discount, you can specify whether to apply a coupon discount, a membership discount, or no discount at all. Learn more with Discounted Ticket Sales (via Coupon or Member)


Example Request

Apply a coupon for $5 off Adult tickets

curl --location --request PUT 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643f4a219f0baf41144ce27d' \
--header 'x-b2c-tenant-id: 123' \
--header 'x-acme-browser-ip: 255.255.255.255' \
--header 'x-acme-api-key: a4c5cfd307834890a6e1e09eb9e11b4d' \
--header 'Content-Type: application/json' \
--data-raw '{
	"id": "643f4a219f0baf41144ce27d",
         "items": [{
               "eventId": "61f99cfb62bd1f467c397829",
               "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5",
               "quantity": 3,
               "couponCodes": [
                    "AAA5"
                ]
         }]
}'

Example Response 

Returns a Shopping Cart Object

{
    "id": "643f4a219f0baf41144ce27d",
    "items": [
        {
            "itemId": "a17766fa6bdc4a0689ee8f170adba6e2",
            "eventId": "61f99cfb62bd1f467c397829",
            "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5",
            "eventName": "Behind-the-Scenes Tour",
            "ticketingTypeName": "Adult",
            "quantity": 3,
            "unitPrice": "27.00",
            "retailUnitPrice": "32.00",
            "amount": "81.00",
            "itemType": "Event",
            "admissionType": "standard",
            "couponCodes": [
                "AAA5"
            ],
            "isRetail": false,
            "ignoreEntitlements": false
        }
    ],
    "forms": [],
    "comboItems": [],
    "verifyEntitlements": false
}


Add a Membership to the Cart

Memberships can be added to a cart for any lifecycle action, including a new purchase, an upgrade, a downgrade, and a renewal.


Things to note:

  • The level, offering, and price point ids must be published IDs. You can find published ids in the membership level list using the published=true flag.
  • You can add the membership to the cart without carholder information. Upon checkout, the shopping cart must contain at least the required primary carholder.


Learn more about Memberships in ACME in our Membership Knowledge Base ›

Prerequisites 

Back Office Setup

To sell a new membership through the B2C checkout API, the membership must be properly configured in Backoffice:

  • The membership level must have a valid offering and price point
  • The offering must have a "New Membership" lifecycle action
  • The B2C sale channel must be enabled for the "New Membership" lifecycle action
  • The membership level must be published


Parameters for a Membership Sale


membershipCategoryId: 
The published id of the selected membership category		Example:
5db23799142c4af6d682187a
membershipOfferingId: (Required)
The id of the selected membership offering
Example: 

f9767e088edd42209ad1af659c9c7d3e

membershipCards: (Required for checkout: Primary Carholder)

A list of membership cards. The number of cards may not exceed the limit specified on the offering in backoffice. Requires one primary cardholder with first name, last name, and zip code, email, or phone number. 


For a full list of membership card fields see Membership Cards. Do not include a constituent import id field unless a matching customer already exists. 

isGift: (Required)
If the membership is a gift, mark as true. If so, gifterInfo is required. 		Example:
gifterInfo: (Required when isGift is true)

A Customer object representing the gift giver. 


You may either search for an existing customer and use that object, or create a new customer for the gifter.  

In order to create a new customer you must populate Customer Source, First, Last and one of (email, address, phone).  

Example:


Optional  Request Parameters
If you want to include optional parameters see Membership Info Object



Example Request - "New" membership purchase

curl --location --request PUT 'https://sandX-api.acmeticketing.net/v2/b2c/carts/63f64233dde09e3b6e1f84d9' \
--header 'x-b2c-tenant-id: 123' \
--header 'x-acme-api-key: a4c5cfd307834890a6e1e09eb9e11b4d' \
--header 'x-acme-browser-ip: 255.255.255.255' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "63f64233dde09e3b6e1f84d9",
    "items":
        {
            "quantity": 1,
            "itemType": "MembershipPurchase",
            "membershipInfo":{
                "membershipCategoryId":"6206e59122895a1d99dba320",
                "membershipOfferingId":"5e58697ca1024ab7b28a745236f869e9",
                "pricePointId":"61786e946476437c5d513068"
            }
        }
    ]
}'



Example Response

Returns the Shopping Cart Object with the Membership Info Object

{
    "id": "643f4a219f0baf41144ce27d",
    "membershipCategoryId": "6206e59122895a1d99dba320",
    "items": [
        {
            "itemId": "7e7a11990aaa41b7bed40786773bf1a4",
            "quantity": 1,
            "unitPrice": "60.00",
            "retailUnitPrice": "60.00",
            "amount": "60.00",
            "itemType": "MembershipPurchase",
            "membershipInfo": {
                "membershipCategoryId": "6206e59122895a1d99dba320",
                "membershipOfferingId": "5e58697ca1024ab7b28a745236f869e9",
                "pricePointId": "61786e946476437c5d513068",
                "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
}