API Reference
Need Help?

placed order

Unlocked Features

  • Order confirmation workflow: Enables you to automate actions when an order is placed.
  • Contact segmentation: Enables targeted communication by categorizing contacts based on specific criteria.
  • Reporting: Helps you to track and analyze the performance and revenue of your campaigns and workflows.

Note: To enable reporting, totalPrice property is required in the event payload.

Supported Endpoints

EndpointeventVersionorigin
/v5/events (Events API)v2api

Example event

Below is an example event provided for testing. You can send this through the available endpoints to evaluate automation, segmentation, or any other custom functionalities.

Events API:


POST /v5/events
Host: api.omnisend.com
Content-Type: application/json

{
  "eventName": "placed order",
  "origin": "api",
  "eventID": "f3f61bc6-07b8-4645-92d8-189d882dbcb1",
  "eventVersion": "v2",
  "eventTime": "2021-07-01T00:00:00Z",
  "contact": {
    "email": "[email protected]"
  },
  "properties": {
    "billingAddress": {
      "address1": "123 Main Street",
      "address2": "123 A Main Street",
      "city": "AnyTown",
      "company": "SuperCompany",
      "country": "USA",
      "firstName": "John",
      "lastName": "Smith",
      "phone": "+443031237300",
      "state": "California",
      "stateCode": "CA",
      "zip": "90210"
    },
    "createdAt": "2023-11-10T07:00:00",
    "currency": "EUR",
    "discounts": [
      {
        "amount": "-",
        "code": "SUMMER20",
        "type": "-"
      }
    ],
    "fulfillmentStatus": "unfulfilled",
    "lineItems": [
      {
        "productCategories": [
          {
            "id": "123",
            "title": "Shoes"
          }
        ],
        "productDescription": "The best product with many various features",
        "productDiscount": 10.19,
        "productID": "1",
        "productImageURL": "https://example.com/product/232423-image.jpg",
        "productPrice": 19.99,
        "productQuantity": 2,
        "productSKU": 200,
        "productTags": [
          "new",
          "sale"
        ],
        "productTitle": "The best product",
        "productURL": "https://example.com/product/232423",
        "productVariantID": "123",
        "productVariantImageURL": "https://example.com/product/232423-variant-image.jpg",
        "productVariantTitle": "Full product title - Green",
        "productVendor": "BestCompany",
        "productWeight": 20.4
      }
    ],
    "note": "Please send it ASAP",
    "orderID": "4122111",
    "orderNumber": "4122111",
    "orderStatusURL": "https://example.com/orders",
    "paymentMethod": "card",
    "paymentStatus": "awaitingPayment",
    "shippingAddress": {
      "address1": "123 Main Street",
      "address2": "123 A Main Street",
      "city": "AnyTown",
      "company": "SuperCompany",
      "country": "USA",
      "firstName": "John",
      "lastName": "Smith",
      "phone": "+443031237300",
      "state": "California",
      "stateCode": "CA",
      "zip": "90210"
    },
    "shippingMethod": "Example Courier",
    "shippingPrice": 2.5,
    "subTotalPrice": 19.99,
    "subTotalTaxIncluded": false,
    "tags": [
      "not-paid"
    ],
    "totalDiscount": 10.19,
    "totalPrice": 15.99,
    "totalTax": 5.99,
    "tracking": {
      "courierTitle": "Example Courier",
      "courierURL": "https://courier-example.com/track-order"
    }
  }
}

Property explanation & expected types

Value PathDescriptionExampleType
billingAddressBilling Address-object
billingAddress.address1Address 1123 Main Streetstring
billingAddress.address2Address 2123 A Main Streetstring
billingAddress.cityCityAnyTownstring
billingAddress.companyCompanySuperCompanystring
billingAddress.countryCountryUSAstring
billingAddress.firstNameFirst NameJohnstring
billingAddress.lastNameLast NameSmithstring
billingAddress.phonePhone+443031237300string
billingAddress.stateStateCaliforniastring
billingAddress.stateCodeState CodeCAstring
billingAddress.zipZip90210string
createdAtCreated At2023-11-10T07:00:00date string
currencyCurrency code in ISO 4217 formatEURstring
discounts[]Discounts-array of objects
discounts[].amountAmount-number
discounts[].codeDiscount code that user has usedSUMMER20string
discounts[].typeType-string
fulfillmentStatusFulfillment status that is recommended to be one of the followings: (unfulfilled, inProgress, fulfilled, delivered, restocked)unfulfilledstring
lineItems[]Order line items-array of objects
lineItems[].productCategoriesProduct Categories-array of objects
lineItems[].productCategories.idId123string
lineItems[].productCategories.titleTitleShoesstring
lineItems[].productDescriptionProduct DescriptionThe best product with many various featuresstring
lineItems[].productDiscountAbsolute value of product discount. I.e if current price is 20 and old price is 30, then discount should be 10.10.19number
lineItems[].productIDProduct ID1string
lineItems[].productImageURLDirect link to product imagehttps://example.com/product/232423-image.jpgstring
lineItems[].productPriceCurrent product price19.99number
lineItems[].productQuantityTotal added quantity2number
lineItems[].productSKUCurrent stock units200string
lineItems[].productStrikeThroughPrice!! This field was removed !!-number
lineItems[].productTagsProduct Tagsnew,salearray of strings
lineItems[].productTitleFull product titleThe best productstring
lineItems[].productURLURL to product pagehttps://example.com/product/232423string
lineItems[].productVariantIDProduct Variant ID123string
lineItems[].productVariantImageURLDirect link to a product variant imagehttps://example.com/product/232423-variant-image.jpgstring
lineItems[].productVariantTitleProduct Variant TitleFull product title - Greenstring
lineItems[].productVendorProduct VendorBestCompanystring
lineItems[].productWeightProduct Weight20.4number
noteAdditional note left by customer or shop adminPlease send it ASAPstring
orderIDOrder ID4122111string
orderNumberOrder Number4122111number
orderStatusURLDirect link where customer can check their order statushttps://example.com/ordersstring
paymentMethodPayment method used by customercardstring
paymentStatusPayment status that is recommended to be one of the followings: (awaitingPayment, partiallyPaid, paid, partiallyRefunded, refunded, voided)awaitingPaymentstring
shippingAddressShipping Address-object
shippingAddress.address1Address 1123 Main Streetstring
shippingAddress.address2Address 2123 A Main Streetstring
shippingAddress.cityCityAnyTownstring
shippingAddress.companyCompanySuperCompanystring
shippingAddress.countryCountryUSAstring
shippingAddress.firstNameFirst NameJohnstring
shippingAddress.lastNameLast NameSmithstring
shippingAddress.phonePhone+443031237300string
shippingAddress.stateStateCaliforniastring
shippingAddress.stateCodeState CodeCAstring
shippingAddress.zipZip90210string
shippingMethodShipping MethodExample Courierstring
shippingPriceShipping Price2.5number
subTotalPriceSub Total Price19.99number
subTotalTaxIncludedSub Total Tax Included-boolean
tagsOrder tags that were added by your shopnot-paidarray of strings
totalDiscountTotal Discount10.19number
totalPriceTotal Price15.99number
totalTaxTotal Tax5.99number
trackingTracking-object
tracking.courierTitleCourier TitleExample Courierstring
tracking.courierURLTracking url where user check check current order status.https://courier-example.com/track-orderstring
tracking.statusStatus-string