With the rise of Customizer and the history using the options table to store everything theme and plugin related, it’s time to get organized. The not so new ability to organize ourselves while developing for WordPress seems to be lacking in the ecosystem. I for one would like to see the community embrace this opportunity to become more organized so we are developing the platform and its bolt on parts with more uniformity, ultimately solving the inherent challenges of mass adoption of both API’s.

Tom McFarlin has written about this recently, below is an excerpt from his post where he shines a light on the topic.

An API For Each Purpose

But what’s the difference? To try to keep this simple:

Theme Modifications represent what’s available for a specific theme. WordPress saves all options managed by The Customizer as a single array in the database.
Options are available to any theme and/or any plugin. In contrast to the Customizer, WordPress saves each value as a single record in the database.
Pretty easy to keep straight, right? I’d go as far as making this case:

If you’re working on a theme, use Theme Modification API (and add support for The Customizer). If you’re building a plugin, use the Options API.

And that’s my general rule of thumb. There are always exceptions, but this is the gist of it.

Why We Have Two APIs

And this is why we continue to have both APIs: One supports themes, one supports plugins.

WordPress Options and Theme Modifications | Tom McFarlin