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

Name

Type

Description

Authorization*

string

Bearer ProductionAccessToken

Request Body

Name Type Description

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.

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.

{
  "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"
}

{
    // Response
}

{
    // Response
}

Shipping & Billing Address

Shipping and billing address objects should contain the following fields:

Key Value Type Desc.

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

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

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

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

Key	Value Type
`new_buyer`	boolean (true/false)
`promo_code`	string

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.

Name

Type

Description

order_id*

string

The ID of the order to be deleted.

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

Name

Type

Description

Authorization*

string

Bearer ProductionAccessToken

{
    // Response
}

{
    // 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.

Name

Type

Description

order_id*

string

The ID of the order to be edited.

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

Name

Type

Description

Authorization*

string

Bearer ProductionAccessToken

{
    // Response
}

{
    // Response
}

PreviousMailing NextDo Not Mail

Last updated 5 months ago