--- updatedAt: 2026-08-25T19:30:45.000Z agentTools: projectIndex: https://loyaltyapi.yotpo.com/llms.txt --- # 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. > 🚧 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 # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "api-settings", "version": "2.0" }, "servers": [ { "url": "https://loyalty.yotpo.com" } ], "components": { "securitySchemes": { "X-API-KEY": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Your account API key can be found in the \"Settings\" section of your Yotpo loyalty admin. See [Yotpo Authentication](https://loyaltyapi.yotpo.com/reference/authentication) to learn how to generate your API key." }, "X-GUID": { "type": "apiKey", "in": "header", "name": "X-GUID", "description": "The Globally Unique Identifier found in the \"Settings\" section of your Yotpo loyalty admin. See [Yotpo Authentication](https://loyaltyapi.yotpo.com/reference/authentication) to learn how to generate your GUID." } } }, "security": [ { "X-API-KEY": [], "X-GUID": [] } ], "paths": { "/api/v2/orders": { "post": { "summary": "Create Order", "description": "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.", "operationId": "create-order", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_email", "total_amount_cents", "currency_code", "order_id", "ip_address", "user_agent" ], "properties": { "customer_email": { "type": "string", "description": "The email address of the customer who placed the order." }, "customer_id": { "type": "string", "description": "The identifier used to uniquely identify the customer in your system. Required if implementing a generic e-commerce integration." }, "total_amount_cents": { "type": "integer", "description": "The total amount the customer spent in cents.", "format": "int32" }, "currency_code": { "type": "string", "description": "The currency used (e.g. 'USD')" }, "order_id": { "type": "string", "description": "An identifier that uniquely identifies the order in your database. The string cannot exceed 255 characters." }, "status": { "type": "string", "description": "Sometimes you might want to separate the removal of points for using a discount code at checkout and the rewarding of points for the order. We will use an order status to determine what we should do." }, "created_at": { "type": "string", "description": "A timestamp describing when this order was placed. Defaults to the current time if not provided." }, "coupon_code": { "type": "string", "description": "A comma separated list of coupon codes used on this order." }, "ip_address": { "type": "string", "description": "The ip address of the customer when they placed the order. This is a fraud prevention measure and required for referral program to work." }, "user_agent": { "type": "string", "description": "The user agent of the customer's browser when they placed the order. This is a fraud prevention measure and is required for the referral program to work." }, "ignore_ip_ua": { "type": "boolean", "description": "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.", "default": false }, "discount_amount_cents": { "type": "integer", "description": "The total amount the customer saved using a discount in cents.", "format": "int32" }, "tags": { "type": "string", "description": "This parameter should include a comma-separated list of order tags. The string cannot be longer than 255 characters" }, "clerk_employee_id": { "type": "string", "description": "The employee identification number of the store clerk who processed the this transaction." }, "clerk_name": { "type": "string", "description": "The first and last name of the store clerk who processed the this transaction." }, "store_address": { "type": "string", "description": "The street name and number of the store's physical location e.g. 123 Main Street" }, "store_city": { "type": "string", "description": "The city name of the store address." }, "store_state": { "type": "string", "description": "The state abbreviation of the store address. e.g. CA" }, "channel_type": { "type": "string", "description": "The channel through which this order was processed. Values can be `online` (off-premise) or `offline` (on-premise brick and mortar store)." }, "items": { "type": "array", "description": "An array of items purchased. Required if you want to run a campaign that requires certain products or collections to be purchased.", "items": { "properties": { "id": { "type": "string", "description": "An identifier that uniquely identifies this product in your database." }, "name": { "type": "string", "description": "The customer facing product name." }, "quantity": { "type": "integer", "description": "The quantity of this product purchased by the customer in this order.", "format": "int32" }, "price_cents": { "type": "integer", "description": "The total price of this item (for 1 quantity) in cents.", "format": "int32" }, "collections": { "type": "string", "description": "A comma separated list of all the collections or tags that this product belongs to." }, "type": { "type": "string", "description": "A category or product type, can be used in filtering for eligibility." }, "vendor": { "type": "string", "description": "The vendor / manufacturer of the product." } }, "required": [ "id", "name", "quantity", "price_cents" ], "type": "object" } }, "customer": { "properties": { "tags": { "type": "string", "description": "This parameter should include comma-separated tags. If you don't have any tags defined, you must still include this parameter." }, "has_account": { "type": "boolean", "description": "Whether the customer has an account with the ecommerce platform. By default set to False" }, "opted_in": { "type": "boolean", "description": "Whether the customer should be opted in to loyalty program. If null, will rely on the account settings of opt in." }, "opted_in_at": { "type": "string", "description": "Date and time the customer opted-in to the loyalty program (iso 8601)", "format": "date" } }, "required": [], "type": "object", "description": "**Required** only if you're excluding or including customers through the Swell admin." } } }, "examples": { "Body Params - Example": { "value": "{\n \"customer_email\": \"john1@example.com\",\n \"total_amount_cents\": \"15000\",\n \"currency_code\": \"USD\",\n \"order_id\": \"testing1\",\n \"status\": \"paid\",\n \"created_at\": \"2019-05-25 20:59:53\",\n \"coupon_code\": \"SAVE5\",\n \"ip_address\": \"127.0.0.1\",\n \"user_agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36\",\n \"discount_amount_cents\": \"500\",\n \"items\": [{\n \"name\": \"Green Shirt\",\n \"price_cents\": \"1499\",\n \"vendor\": \"coolshirts,inc\",\n \"id\": \"472361372358\",\n \"type\": \"shirt\",\n \"quantity\": 2,\n \"collections\": \"new_arrivals,new\"\n }]\n}" }, "With Item/Customer Params": { "value": "{\n \"customer_email\": \"john1@example.com\",\n \"total_amount_cents\": \"15000\",\n \"currency_code\": \"USD\",\n \"order_id\": \"testing1\",\n \"status\": \"paid\",\n \"created_at\": \"2019-05-25 20:59:53\",\n \"coupon_code\": \"SAVE5\",\n \"ip_address\": \"127.0.0.1\",\n \"user_agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36\",\n \"discount_amount_cents\": \"500\",\n \"items\": [{\n \"name\": \"Green Shirt\",\n \"price_cents\": \"1499\",\n \"vendor\": \"coolshirts,inc\",\n \"id\": \"472361372358\",\n \"type\": \"shirt\",\n \"quantity\": 2,\n \"collections\": \"new_arrivals,new\"\n }],\n \"customer\": {\n \"tags\": \"wholesale,non-loyalty\",\n \"has_account\": \"true\",\n \"opt_in\": \"true\",\n \"opted_in_at\": \"2019-05-25 20:59:53\"\n }\n}" } } } } }, "responses": { "201": { "description": "201", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } }, "400": { "description": "400", "content": { "text/plain": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } }, "x-internal": false } } }, "x-readme": { "headers": [ { "value": "application/json", "key": "Content-Type" } ], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```