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

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

Request Body

Name	Type	Description
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.

201 Created

{
  "id": "d32f3be1-b376-4802-99cb-6fa1fc529aca",
  "order_id": "9ca6e9ab-9de6-4491-82c3-8730e2aedfbb",
  "currency": "USD",
  "total": "126.0",
  "customer": {
    "id": "27876",
    "email_sha256": "b043f7b1894189c3591ed2514fcf901ec0de715e8c0c981b893e7d3778d318d4"
  },
  "metadata": {
    "firstTimeOrder": "true"
  },
  "order_items": [
    {
      "category": [
        "Grocery",
        "Fruit"
      ],
      "description": "Handcrafted Wooden Pants",
      "identifier": "88fcae48-b6f3-41d5-826d-1f7ec2a108ba",
      "metadata": {
        "productMaterial": "Cotton"
      },
      "price": "0.0",
      "quantity": 1,
      "total": "504.0"
    },
    {
      "category": [
        "Health",
        "Sports",
        "Toys"
      ],
      "description": "Tasty Plastic Bike",
      "identifier": "94820c46-644e-408f-8f61-4e057a148c5e",
      "metadata": {},
      "price": "483.0",
      "quantity": 1,
      "total": "297.0"
    }
  ],
  "shipping_address": {
    "company": null,
    "address_1": "03055 Williamson Gardens",
    "address_2": "Suite 249",
    "city": "South Maritzaville",
    "state_name": "TN",
    "postal_code": "10843"
  },
  "billing_address": {
    "company": null,
    "address_1": "59184 Henri Canyon",
    "address_2": null,
    "city": null,
    "state_name": "",
    "postal_code": "36670-7309"
  },
  "order_date": "2019-09-05T14:06:42Z"
}

400: Bad Request Incorrectly formatted or missing data

{
    // Response
}

403: Forbidden Incorrect or missing auth header

{
    // Response
}

Shipping & Billing Address

Shipping and billing address objects should contain the following fields:

Key	Value Type	Desc.
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.

Key	Value Type	Desc.
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.

Key	Value Type
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_buyeryour 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

Name	Type	Description
order_id*	string	The ID of the order to be deleted.

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Order Deleted

{
    // Response
}

404: Not Found Order does not exist or ID is incorrect

{
    // Response
}

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

Name	Type	Description
order_id*	string	The ID of the order to be edited.

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Order successfully updated

{
    // Response
}

404: Not Found Order does not exist or ID is incorrect

{
    // Response
}