Subscription Lookup By Customer Id
- Bettina Lippisch
Summary
This service returns all available subscription information stored for a given Customer Id and optional Product Id. Note, this includes both current subscription and deactivated subscriptions (see below to determine the differences).
Note
This service only returns Product types that create a Subscription. Currently only Magazine (productType=1) and Newsletter (productType=2) type products create Customer Subscriptions
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}/subscription/*
Production: https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/subscription/product/{productId}/*Testing: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/subscription/*
Testing: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/customer/{customerId}/subscription/product/{productId}/*brandAbbreviationis the abbreviation for the brandcustomerIdis 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-typea 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 application/json.JSONapplication/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:GETSee W3C’s GET specs for details.
Lookup Subscriptions By Customer Id
Retrieves a record containing all demographic information about the customer.
Field Definition
The following tables describe the hierarchical data elements.
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.
Subscriptions Elements
Element Name | Description |
|---|---|
Customer | Element containing an http reference to the owning customer resource. |
Subscription | each Subscription element contains all subscription information. |
Subscription Elements
Element Name | Optional? | Data Type | Description |
|---|---|---|---|
Id | no | integer | unique subscription identifier |
ProductId | no | integer | Explicit Omeda product id for the product being requested. Only Magazines (productType=1) and Newsletters (productType=2) will be returned via this API. Use the OptLookup API for Email Deployment updates (productType=5). |
RequestedVersion | no | String | “P” for print, “D” for digital, “B” for both |
RequestedVersionCode | no | String | “P” for print, “D” for digital, “B” for both |
ActualVersionCode | no | String | “P” for print, “D” for digital, “B” for both |
Quantity | yes | integer | the number of subscriptions requested |
DataLockCode | yes | Integer | 0 = standard / not locked, 1 = locked (subscription cannot be updated while locked) |
Receive | no | short (boolean) | 0 = subscription not received, 1 = subscription 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’. |
MarketingClassId | yes | String | Indicates whether the subscription is active, controlled, paid, killed etc. This is related to the Marketing Class Description. |
MarketingClassDescription | yes | String | Marketing Class description. |
DeploymentTypes | yes | array | each DeploymentType element contains all deployment type and opt-in/opt-out information. |
ShippingAddressId | yes | Integer | Internal ID of the postal address associated with this subscription. |
BillingAddressId | yes | Integer | Internal ID of the billing address associated with this subscription. |
BillingName | yes | String | Name on the credit card associated with this subscription. |
EmailAddressId | yes | Integer | Internal ID of the email address associated with this subscription. |
ChangedDate | no | Date | Date & time record last changed. yyyy-MM-dd HH:mm:ss format. Example: 2010-03-08 21:23:34. |
Relationships | yes | Integer | Each Relationship element contains the ID and Product Id associated to the complimentary products that were included with the subscription as part of a promotion or default offering. |
PaymentStatus | yes | Integer | Payment status of the subscription, if it is a PAID subscription. This element will be omitted from response if there is no payment status associated with the subscription. Payment Status Codes |
CreditBalance | yes | Decimal | Amount, in USD, of remaining balance the subscriber owes for the subscription. Field will be omitted from response if there is no credit balance associated with the subscription. |
Amount | yes | Decimal | Amount, in USD, the subscriber paid for the subscription. Field will be omitted from response if there is no amount associated with the subscription. |
LastPaymentDate | yes | Date | Returns the date of the most recent payment that was received for a subscription. |
LastPaymentAmount | yes | Decimal | Returns amount in USD of the most recent payment for a subscription. |
LastIssueEarnedDescription | yes | String | Short description of the issue. This is sometimes represented as a short date, sometimes as a number. Field will be omitted from response if there is no issue description associated with the subscription. |
LastIssueEarnedDate | yes | Date | Last issue date. |
FirstIssueEarnedDescription | yes | String | Short description of the issue. This is sometimes represented as a short date, sometimes as a number. Field will be omitted from response if there is no issue description associated with the subscription. |
FirstIssueEarnedDate | yes | Date | Date of the first issue. |
Term | yes | Integer | Length of the subscription using the product’s unit of measure. Field will be omitted from response if there is no term associated with the subscription. |
IssuesRemaining | yes | Integer | Projected number of issues remaining. Field will be omitted from response if there are no issues remaining associated with the subscription. |
CopiesRemaining | yes | Integer | Projected number of copies remaining. Field will be omitted from response if there are no copies remaining associated with the subscription. |
IssueExpirationDate | yes | Date | The projected expiration date for issue-based (print/digital) products. Date & time record last changed. yyyy-MM-dd HH:mm:ss format. Example: 2010-03-08 21:23:34. Field will be omitted from response if there is no projected expiration date associated with the subscription. |
OrderDate | yes | Date | The date that the most recent order was entered for this subscription. 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 subscription. |
OriginalOrderDate | yes | Date | The date that the first order was entered for this subscription. 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 subscription. |
ExpirationDate | yes | Date | The expiration date for continuous-access (i.e. website, online access etc.) products. Date & time record last changed. yyyy-MM-dd HH:mm:ss format. Example: 2010-03-08 21:23:34. Field will be omitted from response if there is no expiration date associated with the subscription. |
DeactivationDate | yes | Date | This date can be used to determine if a Paid subscription has been given extended temporary access. 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 deactivation date associated with the subscription. |
AutoRenewalCode | yes | int | The code for if the subscription is an Auto Renewal. Valid Values are : 0 = Not Auto Renewal, 5 = Auto Charge, 6 = Auto Bill Me on Invoice |
NumberOfInstallments | yes | Integer | The number of installments on a Paid Subscription. Default is always 1, meaning the account is paid all at once. Anything greater that 1 is the number of expected payments. |
InstallmentCode | yes | Integer | The type of Installment Billing Code. Valid Values: 1=Installment Bill Me, 2=Installment Auto Charge) |
Voucher | no | string | this will only be returned if the product was paid for with a Voucher. |
DonorId | no | Integer | The Omeda Customer Id of the Donor who purchased the this Subscription, this will only be returned if the subscription was a Gift Subscription |
GiftMessage | no | String | The Gift Message if it was included at time of gift purchase, this will only be returned if the subscription was a Gift Subscription |
GiftSentDate | no | Date | The Date the gift was sent, this will only be returned if the subscription was a Gift Subscription |
VerificationDate | yes | Date | Verification Date of subscription. |
VerificationAge | no | Integer | Verification Age of subscription. (1, 2, 3, or 4 years. 4 years indicates 4 or more.) 1 is returned if the verification date is in the future or less than 1 year from the audit issue. 4 is return if verification date is 4 *or more* years away from the audit issue. |
Status | no | Integer | The Status represent the current state of the subscription (1 – Active, 2 – Pending, 3 – Expired, 4 – Cancelled, 5 – Graced, 6 – Standing Order) |
SourceId | yes | Integer | SourceId represents the BPA Source (e.g. 23 = Personal direct request electronic [see DataSourceConstants.java]) |
ClientOrderId | no | String | Client transaction id for the order |
RenewalCount | yes | Integer | Number of times a subscription has been renewed |
PremiumCode | no | Integer | Premium code id |
PremiumCodeDescription | no | String | Description of Premium code |
DeploymentType Elements
Element Name | Optional? | Data Type | Description |
|---|---|---|---|
Id | no | integer | unique deployment type identifier |
In | no | integer | For this deployment type, 0 = opt-in absent, 1 = opt-in present |
Out | no | integer | For this deployment type, 0 = opt-out absent, 1 = opt-out present |
Relationship Elements
Element Name | Optional? | Data Type | Description |
|---|---|---|---|
Id | no | integer | unique relationship identifier |
Product Id | no | integer | internal id that identifies the complimentary product |
Response
HTTP Response Codes
Status | Description |
|---|---|
200 OK | The request has succeeded. See Example Response below. |
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. |
500 Internal Server Error | In 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/*",
"Subscriptions":[
{
"Id":472517,
"ProductId":7,
"DataLockCode":0,
"RequestedVersion":"P",
"Quantity":1,
"Receive":1,
"ChangedDate": "2015-03-08 21:23:34",
"ShippingAddressId" : 123673467,
"EmailAddressId" : 22176763,
"VerificationDate" : "2012-03-08",
"VerificationAge" : 4,
"DeploymentType":[
{
"Id":4502,
"In":1,
"Out":0
}
]
},
{
"Id":472518,
"ProductId":8,
"RequestedVersion":"D",
"Quantity":1,
"Receive":0,
"ChangedDate": "2015-03-08 21:23:34",
"ShippingAddressId" : 762347823,
"EmailAddressId" : 780459255,
"DeploymentType":[
{
"Id":4503,
"In":0,
"Out":1
}
]
}
]
"SubmissionId" : "24B9BF6F-0677-462B-942A-D87EEBD10F77"
}
Sample response showing a paid magazine subscription, paid on order, that has 2 remaining issues and a credit balance of $24.00
Sample response showing an active controlled subscription.
Sample response showing a paid continuous website access subscription currently active. Note that this request contains an ExpirationDate field that refers to when the service to the subscription expires. Note also that there is an IssueExpirationDate field as well. Even though website access is thought of as continuous by the consumer, it is still earned financially on a periodic basis (i.e. earning takes place on “virtual issues”), and thus this information is also available. If you are trying to decide which field to use for allowing access to the website, use the ExpirationDate instead of IssueExpirationDate.
Failure
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.
Additional Information
Payment Status Codes
value | description | what it means |
|---|---|---|
1 | Paid on invoice. | Customer paid after being invoiced. |
2 | Paid with order. | Customer paid at the time of his order. |
3 | Credit. | Customer owes an outstanding balance on the subscription. |
5 | Grace. | Customer subscription is in grace. |
6 | Free. | Customer is being granted a free subscription, but isn’t necessarily qualified by the publisher. |
7 | Controlled. | Customer was selected by publisher to receive subscription for free. |
8 | Free Term. | Customer was granted a paid subscription at no cost. (free with expire date, formerly known as Comp) |
Marketing Class Codes
value | Description | Considered Active? | applies to |
|---|---|---|---|
1 | Active. For controlled magazine products, 1 denotes Active Controlled. | yes | All product types. |
2 | Active Non-Qualified | yes | Only products with paid circulation. |
3 | Qualified Reserve | no | Only products with controlled circulation. |
8 | Soft controlled kills | no | Only products with controlled circulation. |
9 | Controlled kills | no | Only products with controlled circulation. |
10 | ACS kills (Address Correction Service) | no | Only products having subscription address delivery. |
20 | Expire suspends | no | Subscription based products having an expiration date. |
21 | Future starts | no | Subscription based products having an expiration date. |
22 | Postal suspends | no | Only products having subscription address delivery. |
23 | Credit Suspends | no | Subscription based paid products. |
24 | Requested Suspends | no | Any product type. |
25 | Kill/Refunds | no | Subscription based paid products. |
50 | Passalong | no | Any product type. |
DeploymentType element – Explained
We have a table that stores the ProductId and DeploymentTypeId relationship. This is a 1-to-1 relationship, so you will only see one DeploymentType element under the DeploymentTypeselement. We query this table using “where ProductId={ProductId}.” We then query our OPT (Opt-In/Opt-Out) table to retrieve the presence of an Opt-In and of an Opt-Out.If no “IN” entries are returned then”In”:0If one or many “IN” entries are returned then”In”:1If no “OUT” entries are returned then”Out”:0If one or many “OUT” entries are returned then”Out”:1
Table of Contents
- 1 Summary
- 2 General Technical Requirements
- 2.1 Base Resource URI
- 2.2 HTTP Headers
- 2.3 Content Type
- 2.4 Supported HTTP Methods
- 3 Lookup Subscriptions By Customer Id
- 3.1 Field Definition
- 3.1.1 Subscriptions Elements
- 3.1.2 Subscription Elements
- 3.1.2.1 DeploymentType Elements
- 3.1.2.2 Relationship Elements
- 3.2 Response
- 3.2.1 HTTP Response Codes
- 3.2.2 Success
- 3.2.3 Failure
- 3.2.3.1 Possible Error Messages
- 3.3 Additional Information
- 3.1 Field Definition