UPCitemdb API

What does UPCitemdb API provide?

UPCitemdb API provides the RESTful interface for you to access our UPC item database. The API currently provides two functions, lookup & search. Each function comes with two RESTful interfaces, HTTP GET and HTTP POST.

What does the API response look like?

For simplicity, UPCitemdb API produces response in JSON. There're only two type of reponses, one for success and one for error. The UPCitemdb API is served from API gateway, in rare case of gateway failure, the gateway might produce error response in html format. But the HTTP status code would be 5xx.

What is lookup function?

lookup function produces item's detail information for a given UPC, EAN, GTIN or ISBN.

What is search function?

search function produces array of items which match the given search phrases. You can also add brand and/or category phrase to filter the search results.

How can I page through the search result?

The maximum array length of the items in each response is 10. The response contains attribute total and offset. Set the offset value in your continuous requests, you'll get the items from offset to offset + 10. If offset is 0, there is no more items. Also the service only returns the top 1,000 matched items if the total matches is more than that.

How do I know my API usage?

Each API response includes headers X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset. For plan Explorer, once daily X-RateLimit-Limit was reached, another header Retry-After, number in seconds, would be set based on X-RateLimit-Reset in unix timestamp. For paid plan, once X-RateLimit-Remaining hits 0, another header X-RateLimit-Current will be set with your current usage for the sepcific function call. If you're on paid plan, you can also login to check the Statistic for usage report. The report graph is rounded to the nearest 10s or 100s per different function calls, while X-RateLimit-Remaining and X-RateLimit-Current reports the exact usage.

What is overage rate?

To avoid service interruption, we provide overage rate for every paid plan. Any requests that exceeds the limits for the specified period in each respective plan will be charged at the overage rate described in each plan. The overage fee will be rounded up to the nearest 10s or 100s hits based on the request type which is described in each plan and will be charged in each next billing cycle together with the monthly-based subscription fee. By default, extra requests over plans' daily limits will be rejected with HTTP status 429. If you wish to extend your account daily limit, please let us know. Overage charge might be incurred after increasing your account's daily limit.

How secure is the API service?

As you might noticed, all pages are served over HTTPS once you landing on the API page. Our credit card payment is powered by Stripe. No credit card data is stored in, or passes through any of our systems. You should keep your API key secret and always set your user_key in the HTTP request HEADER which is encrypted by HTTPS.

What is the difference between the free EXPLORER and the paid plans?

Our API service starts from the FREE plan EXPLORER which allows your application to send 100 requests per day. You have the same full access to our database as the paid plans. The requests and the responses are almost the same for both free and paid plan, except that the paid plan requires an API key (user_key, key_type) to be set in the request HEADER in order to access a different url path (/prod/v1 vs /prod/trial). The FREE plan doesn't require sign up. You can start sending request now. The API Explorer serves as an interactive document which helps you understand the API. For more details on each plan's capacity, please check the plan comparison.

Why do I receive TOO_FAST when I did not hit the daily limit?

To ensure fair usage, a Burst Limit is added to each plan on top of the Daily Limit. For plan DEV, the burst limits are measured in 30 seconds window. Your application is limited to 15 lookup requests and 5 search requests in that period. Once requests hit the burst limits, application should wait for the next 30 seconds window. Also, the response header fields X-RateLimit-xxx would provide the burst limit information instead of daily limit in this case. The burst limits are subject to change to better serve majority applications.

Why did I receive an invoice when I did not make any request?

Our paid plans are subscription-based. The subscription fee is billed immediately at the beginning of the month or at the beginning of any pro-rated billing period. We suggest you not to sign up for the paid plan during your evaluation or development phase.

Why doesn't the API return the information from eBay while the web site shows it, ex. UPC 888462079525?

upcitemdb.com participates eBay Partner Network. Bound by affiliate and network agreements, we're allowed to provide the sales information from eBay on our web site only but cannot redistribute the information.

Failed to save credit card information?

We're using Stripe as our payment gateway. If you kept receiving "Required parameter missing: token", the process might be blocked by your country's Border Firewall. You need to set up your browser with some proxy.

What is your cancellation policy?

You must notify UPCitemdb of your intent to cancel API Services at least 2 business days before your Billing Date. If notice is not received 2 business days before your Billing Date, you will continue to receive your subscription benefits until the end of the current billing period. You will not receive a refund of any portion of the subscription fees you paid for the current or prior billing periods. Business days are 8 AM to 6 PM PST, Monday through Friday, excluding nationally recognized holidays. Please refer Fees & Billing for more details.

Cancellation must be performed by sending an email to api@upcitemdb.com specifying the account name and application name. For verification purpose, request must be sent from the account holder's email address or from the API account.

Ready for the code? »