TABLE OF CONTENTS
- Introduction
- Endpoints
- Create a New Shopping Cart
- Get a Shopping Cart
- Update a Shopping Cart
- Additional Examples
- Create a Shopping Cart with a Donation
- Create a Shopping Cart with an Add On
- 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
- Multiple Events with different Forms configured
- Multiple Events with same Form configured to show "Once Per Cart"
- Multiple Events with same form configured to show "Once Per Event"
- Update a Shopping Cart with an Applied Coupon
- Add a Membership to the Cart
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 Cart (empty of with items) | POST /v2/b2c/carts |
Get a Shopping Cart | GET /v2/b2c/carts/{id} |
Update a Shopping Cart | PUT /v2/b2c/carts/{id} |
- Create a Shopping Cart with a Donation
- Update a Shopping Cart with an Event Ticket
- Update a Shopping Cart with an Event Ticket and Event Add-On
- Update a Shopping Cart with a Form
- Update a Shopping Cart with an Applied Coupon
- Add a Membership to the Cart
Create a New Shopping Cart
POST /v2/b2c/carts
Description
The ACME Shopping Cart helps you collect and manage items that users select as they navigate through the purchase flows.
Things to note:
- To create an empty shopping cart, pass an empty object {} into the create a new shopping cart call.
- If you would like to incorporate member pricing, see examples in Discounted Ticket Sales (via Coupon or Member)
Required Headers
x-b2c-tenant-id
x-acme-api-key
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. See Shopping Cart Object for what fields are required for each object. |
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
Example - Create a New Empty 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": [ ] }'
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:
- This is a full cart update. You must include the full cart contents, not only the changes.
- If you would like to incorporate member pricing, see examples in Discounted Ticket Sales (via Coupon or Member)
Required Parameters
items[ ] (Required) A list of items in the shopping cart. See Shopping Cart Object for what fields are required for each object. |
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 configured 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 for more information.
And overall, learn more about donations with Donation Configuration
Example Request with just the Required fields
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": [ { "type": "fixedDonation", "itemType": "Inventory", "inventoryId": "3572", "quantity": "1", "unitPrice" : "5.00", "amount": "5.00" } ] }'
Example Request with Required and some Optional fields
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
641b51a34649955db8ed9749
Update a Shopping Cart with an Event Ticket
{ "id": "661eb53b1336ce6d98ec1b95", "items": [ { "eventId":"6594494cfd0f3e13c4968b1a", "ticketingTypeId": "5ec3186f221490215acdf36c", "quantity": "2" } ] } } ] }
Update a Shopping Cart with an Event Ticket and Event 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 of the event the Add-On is tied to.
Fields required to add an Add-On:
1. inventoryId
2. itemType ('Inventory')
3. quantity
4. eventId
Example Payload showing only the Required Fields (this is adding an Event Add-On, therefore there is also an Event Ticket in the cart):
{ "id": "661eb53b1336ce6d98ec1b95", "items": [ { "eventId":"6594494cfd0f3e13c4968b1a", "ticketingTypeId": "5ec3186f221490215acdf36c", "quantity": "2" }, { "inventoryId": "4619", "quantity": "1", "itemType": "Inventory", "eventId":"6594494cfd0f3e13c4968b1a" } ] } } ] }
Example Payload showing Required and some Optional fields:
{ "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, } ], }
Update 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 to the event it is associated with
One Event with a Form
{ "id": "661eb53b1336ce6d98ec1b95", "items": [ { "eventId":"6594494cfd0f3e13c4968b1a", "ticketingTypeId": "5ec3186f221490215acdf36c", "quantity": "2", "itemId": "ced1ec9d05264c43aebc8844458d0f44" } ] } } ], "forms": [ { "formId": "661d80edc96539252664a1b0", "formResponseId": "661ec4e7648e4667a486e458", "itemId": "ced1ec9d05264c43aebc8844458d0f44", } ] }
Multiple Events with different Forms configured for each Event
{ "id": "661eb53b1336ce6d98ec1b95", "items": [ { "itemId": "6594494cfd0f3e13c4968b3b", "eventId": "5ec3184fe8827e0ed34fbca0", "ticketingTypeId": "55268c54e4b0fb9be01106bd", "quantity": 1, }, { "itemId": "64d36cd94b501c7be374422a", "eventId": "5ec31bd0d2302445a258962d", "ticketingTypeId": "55268c54e4b0fb9be01106bd", "quantity": 1, } ], "forms": [ { "formId": "6435cdd41be34d4cf366d1d4", "formResponseId": "661d6f9e30570b6212dc5fb3", "itemId": "6594494cfd0f3e13c4968b3b", "oncePerCart": true }, { "formId": "64e7d2a07f5de041ce0cf7c9", "formResponseId": "661d6fc330570b6212dc5fb4", "itemId": "64d36cd94b501c7be374422a", "oncePerCart": false } ]
Multiple Events with same Form configured to show "Once Per Cart"
{ "id": "5e173d6060309f41499e6602", "items": [ { "itemId": "6594494cfd0f3e13c4968b43", "eventId": "5ec3184fe8827e0ed34fbca0", "ticketingTypeId": "55268c54e4b0fb9be01106bd", "quantity": 2, }, { "itemId": "65e087aa84b3b952bad828db", "eventId": "56fab8a868d6097d2a7f4740", "ticketingTypeId": "55268c54e4b0fb9be01106bd", "quantity": 1, } ], "forms": [ { "formId": "6435cdd41be34d4cf366d1d4", "formResponseId": "661d653830570b6212dc5fa6", "itemId": "6594494cfd0f3e13c4968b43", "oncePerCart": true }, { "formId": "6435cdd41be34d4cf366d1d4", "formResponseId": "661d653830570b6212dc5fa7", "itemId": "65e087aa84b3b952bad828db", "oncePerCart": true } ], }
Multiple Events with same form configured to show "Once Per Event"
{ "id": "5e173d6060309f41499e6602", "items": [ { "itemId": "6594494cfd0f3e13c4968b43", "eventId": "5ec3184fe8827e0ed34fbca0", "ticketingTypeId": "55268c54e4b0fb9be01106bd", "quantity": 2, }, { "itemId": "65e087aa84b3b952bad828db", "eventId": "56fab8a868d6097d2a7f4740", "ticketingTypeId": "55268c54e4b0fb9be01106bd", "quantity": 1, } ], "forms": [ { "formId": "6435cdd41be34d4cf366d1d4", "formResponseId": "661d653830570b6212dc5fa6", "itemId": "6594494cfd0f3e13c4968b43", "oncePerCart": false }, { "formId": "6435cdd41be34d4cf366d1d4", "formResponseId": "661d653830570b6212dc5fa7", "itemId": "65e087aa84b3b952bad828db", "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: (Required) 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: true or false |
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 }