This tutorial is intended for view on larger devices.
This tutorial walks you through how to use Bronto’s REST API to abandon a shopping cart, which will trigger any cart abandonment workflows you may have. It is important that your order data for a cart is current so that a contact receives a message with relevant order data, so this tutorial includes steps for Adding or Updating the cart before you abandon it.
In order to use Bronto’s REST API to do shopping cart abandonment you need to have an account that uses Bronto’s New Order Service. If you have the Cart Recovery app, you are using New Order Service.
You also should have successfully set up your commerce configuration settings so that your site is connected to Bronto. All of your commerce configuration settings can be found and modified by logging into the platform and navigating to Home->Settings->Commerce.
If you want the platform to complete an action when you use the API to abandon a cart, your account will need to have a workflow that starts with a Cart Is Abandoned trigger and have created any assets that workflow needs, such as an email the workflow will send. You can create a workflow by logging into the platform and going to Automation->Workflows.
The code in this tutorial uses PHP version 5.3.23 and the following libraries. In order to use this example, as written, you will need to make sure your PHP environment has these libraries installed.
- cURL http://php.net/manual/en/book.curl.php
- JSON* http://php.net/manual/en/book.json.php
*These libraries are usually installed and enabled by default
Setup Hallmonitor Client
If you haven’t already, you need to set up Hallmonitor in order to be able to authenticate and work with Bronto’s REST API. Hallmonitor is an OAuth 2.0 compliant service that is used to request and refresh access tokens for Bronto’s APIs. You must create a client key and client secret for Hallmonitor in order to authenticate with Hallmonitor and get an API token.
- In the Bronto platform, navigate to Home > Settings > Data Exchange.
- Under the REST Integrations section, click Create New Integration.
- Enter a Client Name.
- Select the appropriate client permissions.
- Click Save.
A client key (ID) and secret are generated and shown on the Data Exchange page. Save the the client key and client secret shown in the REST Integrations section of the Data Exchange page. You will use it in a later step to create an API token.
Set Global Variables
Map the string variables you will use to construct requests and store responses in the following steps. This isn’t strictly required, but it will save you from having to type these string variables multiple times.
Because we are adding, updating, and abandoning a cart in this tutorial we’ve provided the variables for each of these calls. However, you will likely only need to either add or update a cart, so you only need to pass the variables relevant to your situation.
Create Response Handlers
You will need to have response handlers for cURL to use so you can get headers from the response later on.
Get Authentication Token
This call returns an authentication token as well as a refresh token to be used once the access token expires. You will need to use this token to access Bronto’s API.
The access token expires after 1 hour. The refresh token expires after 30 days.
Use Token To Authenticate With Bronto’s API
Each request to the external API must include the following HTTP headers:
- Authorization header: The header value should specify a “Bearer” authorization scheme followed by a space and then the OAuth2 access token.
- Content type header: This should be set to application/json.
In order to abandon a Cart, the Cart and its data must be stored in Bronto. If your Cart data is already in Bronto, skip to the next step. Otherwise, add your Cart to Bronto.
When you add the Cart, first build the request data, making sure to match the Bronto defined names for each field. The example provided shows every valid field you can pass in for a Cart. Note, Carts in a COMPLETE or EXPIRED status cannot be updated or abandoned. If you are adding a new Cart you probably want it in the ACTIVE status, which is also the default status if none is provided.
When you add the Cart, only set createContact to true if the Contact does not already exist in Bronto. If createContact is true and you provide an emailAddress that is not currently associated with a Contact, a transactional contact will be created. A transactional Contact can only be sent transactional emails until the Contact opts in to receiving messages from you, so make sure any message that is sent to this type of contact using the Cart Is Abandoned workflow has been approved for transactional sending.
After you have added the Cart, check the response to make sure your request was successful. If it was not, use the information provided in the response to troubleshoot you issue. Generally, if you have an issue adding an order it’s because the customerCartId already existed in Bronto or not all of the required data was included in the request. If it was successful, retrieve the cart ID from the response and then assign the YOUR_CART_ID variable. You will need the ID to abandon the cart.
Now that we have a Cart in Bronto, there a few ways it can be abandoned. When a Cart is added, a timer is started to keep track of how often Bronto sees any activity or updates on the Cart. Based on the rules defined by the user in the Settings page of the Cart Recovery App, Bronto can automatically mark the Cart as abandoned once it has been idle or unchanged for long enough.
A Cart can also be abandoned directly by sending an Abandon Cart request as shown here.
Fiddling a Cart is optional. As described in the previous step, when a Cart is added to Bronto a timer is started to keep track of often the Cart is updated. If you would like to tell Bronto that the Cart is still ‘ACTIVE’ and therefore should not be abandoned but don’t have any actual changes to make on the Cart via an update, you can fiddle the Cart instead as show here. If the Cart is in the ‘ABANDONED’ state upon sending the fiddle request, the Cart will be moved back to the ‘ACTIVE’ status. Note, a Cart can be re-abandoned once it has been brought back to ‘ACTIVE’.
When your customer completes the checkout process on your site, you can complete the Cart in Bronto. This will mark the Cart and ‘COMPLETE’ and prevent any further updates or status changes. Note, when using the API, completing a Cart will not automatically create a corresponding Order. You must make an additional call to add an Order. See the Add or Update Orders tutorial for details on how to do that.