This tutorial is intended for view on larger devices.
This tutorial is designed to help you understand how to manipulate cart data using Bronto’s REST API. You do not need to Add, Get, and Update carts every time you work with cart data. Instead, refer to the action that is relevant to what you are trying to accomplish. In order to work with cart data your account needs to have the New Order Service.
In order to use Bronto’s REST API to work with cart data 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.
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 and updating 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. For example, if you only want to add an order you would not include the GET_UPDATE_CART_ENDPOINT or YOUR_CART_ID.
Create Response Handlers
You will need to have response handlers for cURL to use in order to 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: This 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.
When you add the cart, first build the request data. The array should include all of the relevant cart data.
Then add the cart to Bronto. If the cart is associated with an existing contact, createContact should be set to false. If you set createContact to true, a transactional contact will be created. A transactional contact can only be sent transactional emails, 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 add the cart, check the response. If successful, retrieve the cart ID from the response. You will need the ID to abandon the cart later on.
View A Cart’s Data
This is optional. The complete cart data is returned when you add and update carts.
When you update a cart, be sure to only include the fields you want to update. The following fields cannot be updated:
- position (line items)
If you pass in empty values for fields that previously had data then that data will be deleted (overwritten). If you pass in an empty array then all of your previous line items will be deleted.
When you update the cart, only set createContact to true if the contact does not already exist in Bronto. If you set createContact to true, a transactional contact will be created. A transactional contact can only be sent transactional emails until they opt in.
Check the response to ensure you did what you meant to do or to see if there were errors.