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 | 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 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 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 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:
- 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
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) The number of these items in the shopping cart | Example: 3 |
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
641b51a34649955db8ed9749
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 }