TABLE OF CONTENTS

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 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 that users select as they navigate through the purchase flows.  


Things to note: 


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: 


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 

Returns the Shopping Cart ID

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
}