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 Name	Required?	Description
ClientCustomerId	conditional	the 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 ClientCustomerId, OmedaCustomerId, or TransactionId is required.
OmedaCustomerId	conditional	the 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 ClientCustomerId, OmedaCustomerId, or TransactionId is required.
TransactionId	conditional	You 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 ClientCustomerId, OmedaCustomerId, or TransactionId is required.
ClientOrderId	optional	Your order id, for traceability.
PromoCode	optional	The promo code used, if any.
RunProcessor (DEPRECATED)	optional	This 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.
Products	optional	Array 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 Name	Required?	Data Type	Description
OmedaProductId	required	long	Explicit Omeda product id for the product being requested.
Quantity	optional	integer	Quantity requested. Assumed to be 1 if not given.
PersonalIdentifier	optional	string	A Personal Identifier for the product. For example, “What is your Eye Color?” Maximum of 50 characters.
Receive	optional	short	1 = 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.
RequestedVersion	optional	char	Applicable only for products that have different versions (‘P’ for print, ‘D’ for digital).
ShippingAddressId	conditional	long	Explicit Omeda postal address id for the customer. Note: if submitted, OmedaCustomerId must be given.
EmailAddressId	conditional	long	Explicit Omeda email address id for the customer. Note: if submitted, OmedaCustomerId must be given.
Filter	optional	Array	Array of product elements (‘order line level information’). Only ONE filter entry needs to be set per Product element.

Filter Elements

Attribute Name	Required?	Data Type	Description
EmailAddress	required	string	The customer’s email address for which the opt-in or opt-out is requested.
DeleteOptOut	optional	integer	0 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:

Status	Description
400 Bad Request	Typically, this error occurs when the request does not follow the specifications.
403 Forbidden	Typically, this error occurs when the credentials are erroneous. Potentially, an incorrect x-omeda-appid.
404 Not Found	Typically, this error occurs with a malformed URL or the resource that is searched for is not found.
405 Method Not Allowed	Typically, 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.

Rule	Action
Receive = 1, DeleteOptOut = 0, OPT has OUT	No action.
Receive = 1, DeleteOptOut = 0, OPT has no OUT	The service inserts an IN record in the OPT table for that product and email address.
Receive = 1, DeleteOptOut = 1	The 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 = 0	The service deletes any IN records for that product and email address. The service then inserts an OUT record for that product and email address.