Skip to content

Search the Omeda Knowledge Base

Print

Order History Lookup by Customer Id

Summary

This API provides the ability look up all available Order History information for a customer by the Customer id or for a specific product if the Product Id is included.   The response will include the http reference to the owning customer resource and Order History details with all purchase information.

Note:

  • This service does not return Products that create a Subscription. Use the Subscription Lookup API for Magazine (productType=1) and Newsletter (productType=2) type products.
  • Use the OptLookup API for opt in/out status for Email Deployment type products (productType=5)

General Technical Requirements

The following technical requirements apply to all requests for this API.

Base Resource URI

Production: https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/orderhistory/*

Production: https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/orderhistory/product/{productId}/*

Testing: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/orderhistory/*

Testing: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/orderhistory/product/{productId}/*

brandAbbreviation

is the abbreviation for the brand

customerId

is the internal customer id (encrypted customer id may also be used.)

productId (optional)

is the product id

HTTP Headers

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.

Content Type

The content type is always application/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:

  1. GET : See W3C’s GET specs for details.

Lookup Order History By Customer Id

Retrieves all Order History information about the customer or for a specific Product if one is included.

Field Definition

The following table describes the hierarchical data elements present on the response from the API.

In addition to the below elements, a SubmissionId element will also be returned with all responses. This is a unique identifier for the web services response. It can be used to cross-reference the response in Omeda’s database.

Purchase History Elements

Element NameDescription
CustomerElement containing an http reference for the product being requested.
Order HistoryEach Order element contains the details for the specific order

Order History Elements

Element NameAlways Returned…Data TypeDescription
ProductIdYesIntegerExplicit Omeda product id for the product being requested
OrdersYesArrayEach Order element contains the details for the specific order

Orders Elements

Element NameAlways Returned…Data TypeDescription
ShippingAddressIdNoIntegerInternal ID of the postal address associated with this order.
EmailAddressIdNoIntegerInternal ID of the email address associated with this order.
RequestedVersionYesString“P” for print, “D” for digital, “B” for both
RequestedVersionCodeYesString“P” for print, “D” for digital, “B” for both
ActualVersionCodeNoString“P” for print, “D” for digital, “B” for both
QuantityNoIntegerthe number of orders requested
SKUYesStringThe SKU used during order entry
Receive YesShort (boolean)0 = order not received, 1 = order received NOTE: this is the primary way of determining whether a customer is or is not CURRRENTLY receiving a product. Customers actively receiving the product currently will have a ‘1’. Someone who is no longer currently receiving the product (but has in the past) will have a ‘0’.
MarketingClassIdNoStringIndicates whether the subscription is active, controlled, paid, killed etc. This is related to the Marketing Class Description.
MarketingClassDescriptionNoStringMarketing Class description.
BillingAddressIdNoIntegerInternal ID of the billing address associated with this order.
ChangedDateYesDateDate & time record last changed. yyyy-MM-dd HH:mm:ss format. Example: 2010-03-08 21:23:34.
PaymentStatusNoIntegerPayment status of the order, if it is a PAID order. This element will be omitted from response if there is no payment status associated with the order. Payment Status Codes
AmountNoDecimalAmount, in USD, the customer paid for the order. Field will be omitted from response if there is no amount associated with the order.
TermNoIntegerLength of the order using the product’s unit of measure. Field will be omitted from response if there is no term associated with the order.
OrderDateNoDateThe date that the most recent order was entered for this order. The Date & time format: yyyy-MM-dd HH:mm:ss format. Example: 2010-03-08 21:23:34. Field will be omitted from response if there is no order date associated with the order.
AutoRenewalCodeNoIntegerThe code for if the order is an Auto Renewal. Valid Values are : 0 = Not Auto Renewal, 5 = Auto Charge, 6 = Auto Bill Me on Invoice
NumberOfInstallmentsNoIntegerThe number of installments on a Paid Order. Default is always 1, meaning the account is paid all at once. Anything greater that 1 is the number of expected payments.
InstallmentCodeNoIntegerThe type of Installment Billing Code. Valid Values: 1=Installment Bill Me, 2=Installment Auto Charge)
DonorIdNoIntegerThe Omeda Customer Id of the Donor who purchased the order, this will only be returned if the order was a Gift Order
GiftMessageNoStringThe Gift Message if it was included at time of gift purchase, this will only be returned if the order was a Gift Order
GiftSentDateNoDateThe Date the gift was sent, this will only be returned if the order
was a Gift Order
VerificationDateNoDateVerification Date of order.
SourceIdNoIntegerSourceId represents the BPA Source (e.g. 23 = Personal direct request electronic)
PremiumCodeNoIntegerPremium code id
PremiumCodeDescriptionNoStringDescription of Premium code

Response

HTTP Response Codes

StatusDescription
200 OKThe request has succeeded. See Example Response below.
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.
500 Internal Server ErrorIn the rare case that there is a server-side problem, this response will be returned. This generally indicates a problem of a more serious nature, and submitting additional requests may not be advisable. Please contact your Omeda Account Representative if the issue continues.

Success

{
   "Customer":"https://ows.omedastaging.com/webservices/rest/brand/FOO/customer/12345/*",
   "OrderHistory":[
      {
         "ProductId":7,
         "Orders":[
            {
               "Id":111111,
               "ShippingAddressId":123673467,
               "EmailAddressId":22176763,
               "RequestedVersion":"P",
               "Quantity":1,
               "Receive":1,
               "MarketingClassId":28114,
               "MarketingClassDescription":"Active Non-Qualified",
               "ChangedDate":"2012-09-28 21:23:34",
               "PaymentStatus":2,
               "VerificationDate":"2012-03-07"
            },
            {
               "Id":111222,
               "ShippingAddressId":123673467,
               "EmailAddressId":22176763,
               "RequestedVersion":"P",
               "Quantity":1,
               "Receive":1,
               "MarketingClassId":28114,
               "MarketingClassDescription":"Active Non-Qualified",
               "ChangedDate":"2012-09-28 21:23:34",
               "PaymentStatus":2,
               "VerificationDate":"2012-03-07"
            }
         ]
      },
      {
         "ProductId":22,
         "Orders":[
            {
               "Id":999999,
               "ShippingAddressId":123673467,
               "EmailAddressId":22176763,
               "RequestedVersion":"P",
               "Quantity":1,
               "Receive":1,
               "MarketingClassId":28114,
               "MarketingClassDescription":"Active Non-Qualified",
               "ChangedDate":"2012-09-28 21:23:34",
               "PaymentStatus":2,
               "VerificationDate":"2012-03-07"
            },
            {
               "Id":999888,
               "ShippingAddressId":123673467,
               "EmailAddressId":22176763,
               "RequestedVersion":"P",
               "Quantity":1,
               "Receive":1,
               "MarketingClassId":28114,
               "MarketingClassDescription":"Active",
               "ChangedDate":"2012-09-28 21:23:34",
               "PaymentStatus":2,
               "VerificationDate":"2012-03-07"
            }
         ]
      }
   ],
   "SubmissionId":"24B9BF6F-0677-462B-942A-D87EEBD10F77"
}

Failure

{
   "SubmissionId":"ec0c2ba6-13f4-4934-8efa-74c2ccb33f1d",
   "Errors":[
      {
         "Error":"No purchases found for customer 12345."
      }
   ]
}
Possible Error Messages

In the event of an error, an error response will be returned. Here are some of the possible responses you might receive.

No Purchases found for customer {customerId}.

Additional Information

Payment Status Codes

valuedescriptionwhat it means
1Paid on invoice.Customer paid after being invoiced.
2Paid with order.Customer paid at the time of his order.
3Credit.Customer owes an outstanding balance on the subscription.
5Grace.Customer subscription is in grace.
6Free.Customer is being granted a free subscription, but isn’t necessarily qualified by the publisher.
7Controlled.Customer was selected by publisher to receive subscription for free.
8Free Term.Customer was granted a paid subscription at no cost. (free with expire date, formerly known as Comp)

Marketing Class Codes

valueDescriptionConsidered Active?applies to
1Active. For controlled magazine products, 1 denotes Active Controlled.yesAll product types.
2Active Non-QualifiedyesOnly products with paid circulation.
3Qualified ReservenoOnly products with controlled circulation.
8Soft controlled killsnoOnly products with controlled circulation.
9Controlled killsnoOnly products with controlled circulation.
10ACS kills (Address Correction Service)noOnly products having subscription address delivery.
20Expire suspendsnoSubscription based products having an expiration date.
21Future startsnoSubscription based products having an expiration date.
22Postal suspendsnoOnly products having subscription address delivery.
23Credit SuspendsnoSubscription based paid products.
24Requested SuspendsnoAny product type.
25Kill/RefundsnoSubscription based paid products.
50PassalongnoAny product type.
Table of Contents