Create Order

This endpoint records an order made by a customer. It will apply the order to all matching active campaigns and award the necessary points and/or discounts.

This awards loyalty points only. To send review requests for the same order, also send it to Core Create order. See the Custom platform: sync orders to Reviews and Loyalty recipe.

Recipes
🛒
Record an order and award points
Open Recipe
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
🚧

Important:

  • Customer Tags validation using the customer parameter is available for Shopify, Bigcommerce, Salesforce Commerce Cloud and Generic platforms.\
    • These include/exclude tags must be configured through the Loyalty & Referrals Admin
  • Order Tags validation is available for Shopify, Magento and Generic platforms.\
    • These include/exclude tags must be configured through the Loyalty & Referrals Admin
📘

Points timing

Points are awarded asynchronously. Orders with a created_at far in the past (for example, before your earning campaigns started) are recorded and count toward total_spend_cents, but may not earn points. To mark the customer as opted in, send customer.opted_in: true.

Body Params
string
required

The email address of the customer who placed the order.

string

Your ID for the customer. Optional: the customer is matched or created by customer_email, and points work normally. Send it if you want to look the customer up by your ID: without it, the customer has no store account ID, so Fetch Customer Details by customer_id returns 404.

int32
required

The total amount the customer spent in cents.

string
required

The currency used (e.g. 'USD')

string
required

An identifier that uniquely identifies the order in your database. The string cannot exceed 255 characters. Resending an order_id that was already recorded for this store is safe: the order isn't counted twice, so you can retry a failed request. A resend doesn't update an order that's already processed (see status).

string

The order's status, for example paid or shipped. It's matched, case-insensitively, against the order statuses set in your Loyalty admin. If none are set, every order is processed. An order whose status doesn't match isn't processed yet: send it again with a matching status and it's processed then. Once an order is processed, a resend is ignored, even with a new status.

string

A timestamp describing when this order was placed. Defaults to the current time if not provided.

string

A comma separated list of coupon codes used on this order.

string

The shopper's IP address when they placed the order. Optional: orders earn points without it. It's used to credit referrals, so a missing value can stop a referral from being credited.

string

The shopper's browser user agent when they placed the order. Optional: orders earn points without it. It's used to credit referrals, so a missing value can stop a referral from being credited.

boolean
Defaults to false

If set to true, this will ignore the ip_address & user_agent fraud checks, allowing a referral to be completed even if no ip_address or user_agent are provided. If these params are provided while set to true, the fraud checks will be ignored.

int32

The total amount the customer saved using a discount in cents.

string

This parameter should include a comma-separated list of order tags. The string cannot be longer than 255 characters

string

The employee identification number of the store clerk who processed the this transaction.

string

The first and last name of the store clerk who processed the this transaction.

string

The street name and number of the store's physical location e.g. 123 Main Street

string

The city name of the store address.

string

The state abbreviation of the store address. e.g. CA

string

The channel through which this order was processed. Values can be online (off-premise) or offline (on-premise brick and mortar store).

items
array of objects

An array of items purchased. Required if you want to run a campaign that requires certain products or collections to be purchased.

items
customer
object

Required only if you're excluding or including customers through the Yotpo Loyalty admin. If you leave customer out, the customer's stored tags are kept.

Responses

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json