This tutorial is intended for view on larger devices.
This tutorial walks you through how to add or update an order using Bronto’s REST API. You do not need to Add, Get, and Update orders every time you work with order data. Instead, consult the steps that are relevant to your needs. All of the code examples in the tutorial are based on PHP, so if you want to use the examples as written be sure to use the correct PHP library.
In order to use Bronto’s REST API to work with order 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 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 later in the tutorial. 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 an order in this tutorial, we’ve provided the variables for each of these calls. However, you will likely want to either add or update a cart – not both- so you only need to pass the variables relevant to your situation. For example, if you just want to add an order you would not include the GET_UPDATE_ORDER_ENDPOINT or YOUR_ORDER_ID.
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.
Add An Order
As you build your request data, make sure to match the Bronto defined names for each field. The example provided shows every valid field you can pass in for an order.
When you add the order, only set createContact to true if you are adding a new contact. If you set createContact to true, 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.
After you have added the order, 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 order ID already existed in Bronto or not all of the required data was included in the request.
Check the response to ensure you did what you meant to do or to see if there were errors.
View An Order’s Data
This is optional. You might want to view an order before you update it so you don’t inadvertently overwrite data you wanted to keep.
The complete order data is returned when you add and update orders.
Update An Order
When you update an order, first build the request data. You can update any of the fields available in the AddOrder request except for cartId, customerOrderId, and orderDate. You only need to supply the Order fields which you wish to update.
Any valid value you provide will replace the existing value. This includes the ‘lineItems’ field as a whole. So if you update the lineItems, please provide all lineItems you wish to associate with the order on each update request.
When you update the order, 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.