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 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. |