Search the Omeda Knowledge Base

< All Topics
Print

API – Add Order

Summary

The Order Queue API provides the ability to post a complete set of order information into an order-processing queue. Note that this service just deposits data into a queue. The remaining back end processing of the data (insertion into the marketing database) happens through a decoupled processing layer and depends on your own individual database configuration. Orders are validated for basic information (quantity, product exists, etc.).

Base Resource URI

For Production, use: https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/orderqueue/*

For Testing, use: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/orderqueue/*

brandAbbreviation is the abbreviation for the brand to which the data is being posted.

Technical Requirements

The HTTP header must contain the following elements: x-omeda-appid a unique id provided to you by Omeda to access your data. The request will fail without a valid id. content-type a content type supported by this resource. See Supported Content Types for more details. If omitted, the default content type is application/json.

Optional header element: x-omeda-inputid a unique id with which to process your request. If absent, the x-omeda-appid’s default inputid will be used. Contact your Omeda Customer Services Representative to obtain an inputid.

Supported Content Types

If omitted, the default content type is application/json. JSON application/json

JSON is the preferred data exchange format, because it is lightweight and, in most cases, faster to process and utilizes less bandwidth. There are many available open-source JSON libraries available. See json.org for details.

Supported HTTP Methods

There is one HTTP method supported: POST See W3C’s POST specs for details.

Field Definition

The following tables describe the hierarchical data elements.

Order Elements

Attribute NameRequired?Description
ClientCustomerIdconditionalthe id of the customer in the external/interfacing system. This id is assumed to be unique within the brand and is used to lookup the record in the Omeda database. Because it is possible that the ClientCustomerId may not refer to an existing customer, it is discouraged to use this field. Order processing will fail if the client customer id does not refer to a customer in the database. One of either ClientCustomerIdOmedaCustomerId, or TransactionId is required.
OmedaCustomerIdconditionalthe id of the customer in the omeda database. This id is unique. Providing this guarantees that identityresolution processing will be bypassed. You should provide this id only if you are certain that the data provided in this call is definitely associated with the individual specified by the id. One of either ClientCustomerIdOmedaCustomerId, or TransactionId is required.
TransactionIdconditionalYou should use the transaction id when you do not have an explicit customer id (either your own or Omeda’s) and have just submitted customer data to be added to the database. The data queue service responsible for adding customers to the database hands back a TransactionId which you should use to make sure this Order is attached to the appropriate data payload. One of either ClientCustomerIdOmedaCustomerId, or TransactionId is required.
ClientOrderIdoptionalYour order id, for traceability.
PromoCodeoptionalThe promo code used, if any.
RunProcessor (DEPRECATED)optionalThis is a deprecated feature and should not be used by new API implementations. 0 or 1, allows for real-time processing of data. 1 = Runs the data processor in real-time. 0 (or no element) = The data processor will run if activated by an account representative.
ProductsoptionalArray of product elements (‘order line level information’).

Product Elements

Send in “Product” elements for Magazine and Newsletter type Products to create a subscription for that Product. If the Product is of type “Email Deployment”, you can use the Product Element and include a “Filter” sub-element to create an Opt-In or Opt-Out entry. Alternately, you can use the Optin API or Optout API to send in “Email Deployment” type Products.

Attribute NameRequired?Data TypeDescription
OmedaProductIdrequiredlongExplicit Omeda product id for the product being requested.
QuantityoptionalintegerQuantity requested. Assumed to be 1 if not given.
PersonalIdentifieroptionalstringA Personal Identifier for the product. For example, “What is your Eye Color?” Maximum of 50 characters.
Receiveoptionalshort1 = opt-in, 0 = opt-out. Assumed to be 1 if not given. Explicitly allows this order service to capture opt-out behaviorsas part of the order transaction.
RequestedVersionoptionalcharApplicable only for products that have different versions (‘P’ for print, ‘D’ for digital).
ShippingAddressIdconditionallongExplicit Omeda postal address id for the customer. Note: if submitted, OmedaCustomerId must be given.
EmailAddressIdconditionallongExplicit Omeda email address id for the customer. Note: if submitted, OmedaCustomerId must be given.
FilteroptionalArrayArray of product elements (‘order line level information’). Only ONE filter entry needs to be set per Product element.
Filter Elements
Attribute NameRequired?Data TypeDescription
EmailAddressrequiredstringThe customer’s email address for which the opt-in or opt-out is requested.
DeleteOptOutoptionalinteger0 or 1, 0 = No delete, 1 = Delete. We highly recommend reading the Additional Information section for details.

Request Examples

In the examples below (JSON and XML), the customer with OmedaCustomerId 129340133423 is signed up for product 101588 because this customer’s “Receive” element is set to 1. The customer is also unsubscribed from product 101589 because the “Receive” element is set to 0 (zero). For product 101588, the customer is opted-in (Filter element) with the email address “jsmith@domain.com.” If the customer already has an opt-out, it will be deleted because of the element “DeleteOptOut” is set to 1. If absent or set to 0, the existing opt-out supersedes the requested opt-in. For an opt-out, no such flag is needed because an opt-out request always supersedes an existing opt-in.

JSON Example

{
  "OmedaCustomerId":129340133423,
  "ClientOrderId":"ORD19520",
  "PromoCode":"ZZZ2010A23",
  "Products":[
    {
      "OmedaProductId":101588,
      "RequestedVersion":"D",
      "Receive":1, 
      "Quantity":1,
      "PersonalIdentifier":"Blue",
      "ShippingAddressId":5423534563,
      "EmailAddressId":54235345356,
      "Filter":[
        {
          "EmailAddress":"jsmith@domain.com",
          "DeleteOptOut":1
        }
      ]
    },
    {
      "OmedaProductId":101589,
      "Receive":0,
      "Filter":[
        {
          "EmailAddress":"jsmith@domain.com"
        }
      ]
    }
  ]
}

Response Examples

Two responses are possible: a successful POST (200 OK Status) or a failed POST (400 Bad Request/403 Forbidden/404 Not Found/405 Method Not Allowed Statuses). See W3C’s Status Codes.

Successful Submission

A successful POST submission will create an Order in the order queue. The response has a ResponseInfo element with two sub-elements, an OrderId element, the Id for the order, and a Url element, the URL that allows you to check the status of the order. See Order Lookup Service for more details.

JSON Example

Without “RunProcessor”:1

{
  "ResponseInfo":[
    {
      "OrderId":12349,
      "Url":"https://ows.omedastaging.com/webservices/rest/brand/FOO/order/12349/*"
    }
  ]
}

With “RunProcessor”:1

{
  "ResponseInfo":[
    {
      "OrderId":12349,
      "Url":"https://ows.omedastaging.com/webservices/rest/brand/FOO/order/12349/*",
      "CustomerId":3349,
      "CustomerUrl":"https://psows.omeda.com/webservices/rest/brand/FOO/customer/3349/*"
    }
  ]
}

Failed Submission

A failed POST submission may be due to several factors:

StatusDescription
400 Bad RequestTypically, this error occurs when the request does not follow the specifications.
403 ForbiddenTypically, this error occurs when the credentials are erroneous. Potentially, an incorrect x-omeda-appid.
404 Not FoundTypically, this error occurs with a malformed URL or the resource that is searched for is not found.
405 Method Not AllowedTypically, this error occurs when the resource accessed is not allowed by the HTTP Method utilized. Make sure you employ the correct HTTP Method (POST) for this request.

This is not an exhaustive list of errors, but common ones. If an error occurs repeatedly, please contact your Omeda representative.

JSON Example

{
  "Errors" : [
    {
      Error": "Product MAGAZINE_ABC not recognized." 
    },
    {
      "Error": "Quantity was a negative number."
    }
  ]	
}

Additional Information

DeleteOptOut Rules

By convention, we use “OPT” to designate our Opt-In/Opt-Out table.

RuleAction
Receive = 1, DeleteOptOut = 0, OPT has OUTNo action.
Receive = 1, DeleteOptOut = 0, OPT has no OUTThe service inserts an IN record in the OPT table for that product and email address.
Receive = 1, DeleteOptOut = 1The service deletes all global and brand level OUT entries for the email address provided. The service then inserts an IN record for that product and email address.
Receive = 0The service deletes any IN records for that product and email address. The service then inserts an OUT record for that product and email address.
Table of Contents
Scroll to Top