# 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](https://app.heypoplar.com/transaction) 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. | {% tabs %} {% tab title="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" } ``` {% endtab %} {% tab title="400: Bad Request Incorrectly formatted or missing data" %} ```javascript { // Response } ``` {% endtab %} {% tab title="403: Forbidden Incorrect or missing auth header" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ### 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 | {% hint style="warning" %} 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. {% endhint %} ### 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* | {% tabs %} {% tab title="200: OK Order Deleted" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found Order does not exist or ID is incorrect" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ## 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* | {% tabs %} {% tab title="200: OK Order successfully updated" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found Order does not exist or ID is incorrect" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %}