Orders
Orders endpoints may be used to report customer transactions as they happen. These are used within Poplar for attribution reporting and to enable existing customers to be easily suppressed within your campaigns.
You can monitor this API integration from the Transactions Page of the dashboard. We provide basic diagnostic information and the ability to purge any transactional data stored within your account.
Submit Order
POST
https://api.heypoplar.com/v1/order
https://api.heypoplar.com/v1/order
Use this endpoint to report a new transaction or order
In addition to the required fields, at least one of the following must be provided: shipping_address
, billing_address
, customer_email_sha256
, or customer_email
Headers
Authorization*
string
Bearer ProductionAccessToken
Request Body
metadata
object
A set of key/value pairs specifying additional information about an order.
shipping_address
object
The customers shipping address.
billing_address
object
The customers billing address.
order_items
array
An array of item details.
currency
string
The three-character ISO country code. If this is not provided, we will assume USD
.
total
number
The total order value represented as a decimal. Since this is used to calculate campaign metrics such as CPA and ROAS, then you may wish to exclude taxes and additional surcharges.
customer_email_sha256
string
The SHA256 hash of the customers email addresses, as a 64 character string. Note that the value of the email address should be converted to lowercase prior to hashing.
customer_email
string
The customers email address. This value is not stored by Poplar. It is used to compute a hash and is discarded.
customer_id
string
The ID for the transacting customer in your system. This is typically unique for this customer.
order_date*
string
YYYY-MM-DD (ISO8601) formatted date representing the time the purchase was made by the customer.
order_id*
string
The unique identifier for this order.
Shipping & Billing Address
Shipping and billing address objects should contain the following fields:
name
string
Optional
address_1
string
Required Address number and street name
address_2
string
Optional Apt/Suite/Unit/etc.
city
string
Optional
state
string
Optional
postal_code
string
Required
country
string
Optional Three-character country code. If not provided will default to USA
Order Items
You may provide order item details with an order. This is optional, however this data is used to add additional dimensions to our reporting.
identifier
string
Required Unique identifier for the item purchased. This may be a UPC or SKU
description
string
Optional Name/Description of the item
quantity
integer
Optional Number of unique units represented by this order item
total
number
Required Total price of unique units purchased of this order item (e.g. price x quantity)
price
number
Optional Unit price of this order item
category
array
Optional An ordered array of strings, starting with the top most category
metadata
object
Optional A set of key/value pairs containing additional information about this item
Metadata
Optional metadata may be provided with Orders and Order Items. This data is used to enhance reporting. For example, you may wish to include a flag which indicates a customer's first time order or segment.
The metadata object should consist of
key : value
pairs.You are permitted up to 10 different keys.
Each key should be a string, up to 40 characters in length.
Values should string, number or boolean types, limited to a maximum length of 200 characters.
We've pre-defined the following keys for advanced reporting.
new_buyer
boolean (true/false)
promo_code
string
If you'd like to have this data in your reports, you must name them exactly as they appear above. For example, if you name the key nb
instead of new_buyer
your reports will NOT show the information.
Customers (Orders API)
When you submit transactions to the Orders API we will also automatically create an audience called "Customers (Orders API)" that will include customers of the orders. The audience will contain two records for each order submitted one with the shipping address, and one with the billing address.
This list is useful when you are mailing prospecting campaigns and want to suppress existing customers that have been submitted to the Orders API. (note unless you have submitted all historical orders it will not be a complete customer list) You cannot mail this audience as a one time send.
Delete Order
DELETE
https://api.heypoplar.com/v1/order/:order_id
https://api.heypoplar.com/v1/order/:order_id
Deletes the specified order by ID.
Path Parameters
order_id*
string
The ID of the order to be deleted.
Headers
Authorization*
string
Bearer ProductionAccessToken
Edit Order
POST
https://api.heypoplar.com/v1/order/:order_id
https://api.heypoplar.com/v1/order/:order_id
Allows updates to be made to the specified order. This method accepts the same parameters as order submission, with the exception of order_id
- this cannot be changed.
Path Parameters
order_id*
string
The ID of the order to be edited.
Headers
Authorization*
string
Bearer ProductionAccessToken
Last updated