Customers

each Customer element contains the customer’s specific data and the subscription information.

OmedaCustomerId

the internal customer identifier

Subscriptions

each Subscription element contains all requested subscription information.

Url

a link reference to the customer data as a resource.

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

Subscription class code – indicating whether the subscription is active, controlled, paid, killed etc. This is related to the Marketing Class Description. Generally the developer will want to use this class in preference to the Marketing Class ID field because these codes tend to be invariant across products. Marketing Class Codes

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, or the subscription Status is not Active.

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

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

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

Id

no

integer

unique relationship identifier

Product Id

no

integer

internal id that identifies the complimentary product

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.

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.

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.

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.

21

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.