Looking to sell discounted tickets using either membership discounts or coupons? You have come to the right place.
We've outlined a series of scenarios to help you understand what to include in the payloads to process the discounts. Additionally, it's possible to mix and match at the ticket level, provided you include the necessary data.
Our endpoints have defaults for all optional parameters, so do keep that in mind when testing your implementation
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
Scenarios
- Update a Shopping Cart & Get Member Pricing for an Event
- Entitlements Validation for a Membership
- Selling Tickets with Membership Discounts
- Selling Tickets with a Coupon Discount
- Member Discounts, Coupon Discounts, and Full Price tickets (all in one)
Update a Shopping Cart & Get Member Pricing for an Event
PUT /v2/b2c/carts/{id}
Description
When you include a Membership ID in the Shopping Cart, you will receive back the calculated member pricing for each ticket.
For more about the shopping Cart, see B2C Shopping Cart.
Parameters
For Required and optional parameters see Shopping Cart Object.
Example
Request
curl --location --request PUT 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643e8cbd9f0baf41144ce26b' \ --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' \ --header 'Cookie: __cf_bm=2hloYj76cX1Hkyy9epkcWfLLHBph8K_IfK_gG6ZfzJ4-1681820889-0-AZa9yIvsFz9ZtO7FN6vR+gypQ3eosubDapKexmTeRL80hOwEbmP0E3u8un2upl3uS/0oNpZeqcNQLWzOKL+jpu4=' \ --data '{ "id": "643e8cbd9f0baf41144ce26b", "membershipIds": [5970603], "items": [{ "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 0 }] }'
Response
Returns the Shopping Cart Object (documentation coming soon)
{ "id": "643e8cbd9f0baf41144ce26b", "items": [ { "itemId": "c5e55f44d52e4154af432fb2571c2add", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 0, "unitPrice": "24.00", "retailUnitPrice": "32.00", "amount": "0.00", "itemType": "Event", "admissionType": "standard", "isRetail": false, "ignoreEntitlements": false } ], "forms": [], "comboItems": [], "verifyEntitlements": false, "membershipIds": [ 5970603 ] }
Entitlements Validation for a Membership
POST /v2/b2c/entitlements/validate
Description
This API helps you understand if the ticket purchases are valid for a certain member, given the entitlements configured for their membership level. It is important to call in the Shopping Cart for ticket purchases in order to validate if there are any Member Rules applied to the tickets. If there are Member Rules (e.g. ticket limits), you will need to let the member know so they can adjust their cart items accordingly. See Configuring Member Rules for Event Discounts for additional information.
Parameters
A populated Shopping Cart Object OR a Shopping Cart ID.
id: (Required) Shopping Cart ID | Example: 640a0be58b9e2f3b7b74b16d |
Example
Request
curl --location 'https://sandX-api.acmeticketing.net/v2/b2c/entitlements/validate' \ --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 '{ "id": "643e8cbd9f0baf41144ce26b" }'
Response
Returns an EntitlementsResult Object which contains validations results. If the results have failed, the response includes information about membership discounts and limits.
{ "valid": false, "messages": [ "Rule failed:Adult_Child_Senior_Student_Youth_1" ], "results": [ { "allowedQuantity": 1, "purchasedQuantity": 0, "requestedQuantity": 2, "valid": false, "ruleSetId": "61f99ce662bd1f467c397745", "rulesApplied": [ { "id": "Adult_Child_Senior_Student_Youth_1", "valid": false, "message": "Rule failed:Adult_Child_Senior_Student_Youth_1", "messageCode": "Adult_Child_Senior_Student_Youth_1-ERROR" } ], "items": [ { "itemId": "9d1629a4a0e14085ab25775651daffb8", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 2, "unitPrice": "0.00", "retailUnitPrice": "0.00", "amount": "0.00", "eventName": "Behind-the-Scenes Tour" } ], "membershipId": 5970603, "membershipLevelId": "6206e59122895a1d99dba320", "timeFrame": "oneDay", "pricepointIds": [ "6130fea5bf4aec4ef5db0dc5", "6130feb25d8fd13115cc3aef", "6130feaa64056f6aa46c4b56", "6130feae0f0de240487a9530", "6130feb55d8fd13115cc3af1" ], "ruleType": "memberBenefits", "validatedPricePointIds": [], "reason": "Cart" }, { "allowedQuantity": 1, "purchasedQuantity": 0, "requestedQuantity": 2, "valid": true, "ruleSetId": "61f99ce662bd1f467c397745", "rulesApplied": [ { "id": "Adult_Child_Senior_Student_Youth_1", "valid": true } ], "items": [ { "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 2, "eventName": "Behind-the-Scenes Tour" } ], "timeFrame": "oneDay", "pricepointIds": [ "6130fea5bf4aec4ef5db0dc5", "6130feb25d8fd13115cc3aef", "6130feaa64056f6aa46c4b56", "6130feae0f0de240487a9530", "6130feb55d8fd13115cc3af1" ], "ruleType": "memberBenefits", "validatedPricePointIds": [] }, { "allowedQuantity": 2, "purchasedQuantity": 0, "requestedQuantity": 2, "valid": true, "ruleSetId": "61f99ce662bd1f467c397745", "rulesApplied": [ { "id": "Adult_Child_Senior_Student_Youth_2", "valid": true } ], "items": [ { "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 2, "eventName": "Behind-the-Scenes Tour" } ], "timeFrame": "oneDay", "pricepointIds": [ "6130fea5bf4aec4ef5db0dc5", "6130feb25d8fd13115cc3aef", "6130feaa64056f6aa46c4b56", "6130feae0f0de240487a9530", "6130feb55d8fd13115cc3af1" ], "ruleType": "memberBenefits", "validatedPricePointIds": [] }, { "allowedQuantity": 3, "purchasedQuantity": 0, "requestedQuantity": 2, "valid": true, "ruleSetId": "61f99ce662bd1f467c397745", "rulesApplied": [ { "id": "Adult_Senior_3", "valid": true } ], "items": [ { "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 2, "eventName": "Behind-the-Scenes Tour" } ], "timeFrame": "oneDay", "pricepointIds": [ "6130fea5bf4aec4ef5db0dc5", "6130feaa64056f6aa46c4b56" ], "ruleType": "memberBenefits", "validatedPricePointIds": [] } ], "violations": [ { "eventId": "61f99cfb62bd1f467c397829", "pricePointId": "6130fea5bf4aec4ef5db0dc5", "allowedQuantity": 1, "purchasedQuantity": 0, "requestedQuantity": 2, "timeFrame": "day", "pricePoints": [ "Adult", "Child", "Senior", "Student", "Youth" ], "ruleType": "memberBenefits", "validatedPricePointIds": [ "6130fea5bf4aec4ef5db0dc5", "6130feb25d8fd13115cc3aef", "6130feaa64056f6aa46c4b56", "6130feae0f0de240487a9530", "6130feb55d8fd13115cc3af1" ], "validatedPricePoints": [ "Adult", "Child", "Senior", "Student", "Youth" ], "reason": "Cart", "pricePointIds": [ "6130fea5bf4aec4ef5db0dc5", "6130feb25d8fd13115cc3aef", "6130feaa64056f6aa46c4b56", "6130feae0f0de240487a9530", "6130feb55d8fd13115cc3af1" ] } ], "passed": [] }
Selling Tickets with Membership Discounts
PUT /v2/b2c/carts/{id}
POST /v2/b2c/checkout
Description
If a membership (via an ID or a purchase) is in the cart, by default membership discounts will be applied to the tickets. This is great if there are no limits on discounted tickets. However, if members are limited in the number of discounted tickets they can purchase, they will need to purchase additional tickets at full price. As such, you will want to specify the pricing and discounts in the shopping cart. The key parameter to specify is the boolean "isRetail".
Parameters
For required and optional parameters see Shopping Cart Object and Checkout Object (coming soon).
Example for a Shopping Cart Update
In this example, we send update the Shopping Cart. The same applies when doing a checkout call with the Shopping Cart Object.
Request
curl --location 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643e8cbd9f0baf41144ce26b'' \ --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 '{ "id": "643e8cbd9f0baf41144ce26b", "membershipIds": [5970603], "items": [ { // Member discounted ticket (25% off) "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1 }, { // Full price ticket "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1, "isRetail": true } ] }'
Response
Returns a Shopping Cart Object with the applicable pricing applied.
{ "id": "643e8cbd9f0baf41144ce26b", "items": [ { "itemId": "b6f180363e9749d8bc39f9e1472ada79", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "24.00", "retailUnitPrice": "32.00", "amount": "24.00", "itemType": "Event", "admissionType": "standard", "isRetail": false, "ignoreEntitlements": false }, { "itemId": "fea3624bb958494cb79c6953c3852c23", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "32.00", "retailUnitPrice": "32.00", "amount": "32.00", "itemType": "Event", "admissionType": "standard", "isRetail": true, "ignoreEntitlements": false } ], "forms": [], "comboItems": [], "verifyEntitlements": false, "membershipIds": [ 5970603 ] }
Selling Tickets with a Coupon Discount
PUT /v2/b2c/carts/{id}
POST /v2/b2c/checkout
Description
Coupons can be applied to the Shopping Cart at either the cart level or ticket level.
- Cart Level - When applying a coupon at the cart level, the system will automatically calculate and apply the coupon to all eligible items. This is very standard for online checkout, as the guest will enter the coupon code once and the cart will apply it to everything eligible.
- Ticket Level - If however, you have a use case where you want to only apply coupons to certain tickets (e.g. perhaps the coupon can only be used on a single ticket), the APIs support this.
Parameters
For required and optional parameters see Shopping Cart Object and Checkout Object (coming soon).
Example for a Shopping Cart Update
In this example, we apply the coupons at the ticket level (one full price and one discounted) via an update to the Shopping Cart. The same applies when doing a checkout call with the Shopping Cart Object.
Request
curl --location 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643e8cbd9f0baf41144ce26b'' \ --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 '{ "id": "643e8cbd9f0baf41144ce26b", "items": [ { // Full price ticket "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1 }, { // Coupon discounted ticket ($5 off) "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1, "couponCodes": [ "AAA5" ] } ] }'
Response
Returns a Shopping Cart Object with the applicable pricing applied.
{ "id": "643e8cbd9f0baf41144ce26b", "items": [ { "itemId": "d41fa0aa4a1a4ef49ed085ca4828868f", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "32.00", "retailUnitPrice": "32.00", "amount": "32.00", "itemType": "Event", "admissionType": "standard", "isRetail": false, "ignoreEntitlements": false }, { "itemId": "cc3d9ac24f4f4c30bba0f3048aa167e7", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "27.00", "retailUnitPrice": "32.00", "amount": "27.00", "itemType": "Event", "admissionType": "standard", "couponCodes": [ "AAA5" ], "isRetail": false, "ignoreEntitlements": false } ], "forms": [], "comboItems": [], "verifyEntitlements": false }
Member Discounts, Coupon Discounts, and Full Price tickets (all in one)
PUT /v2/b2c/carts/{id}
POST /v2/b2c/checkout
Description
The following example is intended to demonstrate how ACME API's rules are applied when a user is trying to buy tickets using a member discount, a coupon and a ticket with full price in the same order.
- Member Discount: With a Membership ID on the shopping cart, the system will automatically apply the member discounted price.
- Coupon Discount: If a coupon is specified, the system will automatically apply the coupon price. This will trump any member discount.
- Full Price: In order to charge full price, specify "isRetail:true".
Parameters
For required and optional parameters see Shopping Cart Object and Checkout Object (coming soon).
Example for a Shopping Cart Update
In this example, we apply update the Shopping Cart. The same applies when doing a checkout call with the Shopping Cart Object.
Request
curl --location 'https://sandX-api.acmeticketing.net/v2/b2c/carts/643e8cbd9f0baf41144ce26b'' \ --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 '{ "id": "643e8cbd9f0baf41144ce26b", "membershipIds": [5970603], "items": [ { // Member discounted ticket (25% off) "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1 }, { // Full price ticket "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1, "isRetail": true }, { // Coupon discounted ticket ($5 off) "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "quantity": 1, "couponCodes": [ "AAA5" ] } ] }'
Response
Returns a Shopping Cart Object with the applicable pricing applied.
{ "id": "643e8cbd9f0baf41144ce26b", "items": [ { "itemId": "cfcdd3cf529f4b9fa65f5f29ee31391a", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "24.00", "retailUnitPrice": "32.00", "amount": "24.00", "itemType": "Event", "admissionType": "standard", "isRetail": false, "ignoreEntitlements": false }, { "itemId": "3e283489c1534118a443b1cacea28c8e", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "32.00", "retailUnitPrice": "32.00", "amount": "32.00", "itemType": "Event", "admissionType": "standard", "isRetail": true, "ignoreEntitlements": false }, { "itemId": "cb456493ab2741458b548fb6704d6df9", "eventId": "61f99cfb62bd1f467c397829", "ticketingTypeId": "6130fea5bf4aec4ef5db0dc5", "eventName": "Behind-the-Scenes Tour", "ticketingTypeName": "Adult", "quantity": 1, "unitPrice": "27.00", "retailUnitPrice": "32.00", "amount": "27.00", "itemType": "Event", "admissionType": "standard", "couponCodes": [ "AAA5" ], "isRetail": false, "ignoreEntitlements": false } ], "forms": [], "comboItems": [], "verifyEntitlements": false, "membershipIds": [ 5970603 ] }