Custom Post Type Permalinks – Part 2

In Custom Post Type Permalinks – Part 1 we considered how to set different permalink options from the register_post_type function call. Here, we focus on how to create our own permalink structures.

With the register_post_type function, we can easily set our custom post type permalink structure to look like this (assuming custom post type = gallery).

However, we may want to fully customize our custom object permalink structure, similar to how we can fully customize our post permalink structure. Suppose we want to set our permalink structures as follows –

Post permalink structure


Gallery custom post type permalink structure


1. Turn Off Default Rewrite Rules

First, we set the rewrite argument to false in our register_post_type function call.

	$args = array(
		'publicly_queryable' => true,
		'query_var' => true,
		'rewrite' => false,

After we set the argument to false, our gallery custom post type will no longer use pretty permalinks. Instead, our links will look like this –

Note – It is also necessary to set query_var to true to enable proper custom post type queries.

2. Add New Custom Post Type Rewrite Rules

To get back our pretty permalinks, we need to add our own %gallery% rewrite tag, and our own gallery perma-structure.

// add to our plugin init function
global $wp_rewrite;
$gallery_structure = '/galleries/%year%/%monthnum%/%gallery%';
$wp_rewrite->add_rewrite_tag("%gallery%", '([^/]+)', "gallery=");
$wp_rewrite->add_permastruct('gallery', $gallery_structure, false);

The add_rewrite_tag function accepts 3 arguments.

  1. tag name – Our custom post type tag name. E.g. %gallery%.
  2. regex – A regular expression that defines how to match our custom post type name.
  3. query -The query variable name to use for our custom post type plus an = at the end. The result of our regular expression above gets appended to the end of our query.

For example, suppose our pretty permalink is –

The result of the regular expression match from %gallery% is test-1. This value gets passed on as a public query to our main blog –

Later, the query link gets translated back into our original pretty permalink so that our end-users are shielded from this whole process.

The add_permastruct function takes in 4 arguments.

  1. name – Name of our custom post type. E.g. gallery.
  2. struct – Our custom post type permalink structure. E.g.
  3. with_front – Whether to prepend our blog permalink structure in front of our custom post type permalinks. If we set with_front to true here, our gallery permalinks would look like this –

    This is not what we want, so we set it to false.

  5. ep_mask – Sets the ep_mask for our custom post type.

Adding the add_permastruct function changes our gallery object permalinks from


which results in a 404 or file not found page error. This is because the permalink tags %year% and %monthnum% were not properly translated.

3. Translate Custom Post Type Permalink Tags

Finally we need to translate the additional tags in our custom post type permalink. To do this, we hook into the post_type_link filter. The code used in our tag translation function was adapted from the regular WordPress post get_permalink function.

// Add filter to plugin init function
add_filter('post_type_link', 'gallery_permalink', 10, 3);	
// Adapted from get_permalink function in wp-includes/link-template.php
function gallery_permalink($permalink, $post_id, $leavename) {
	$post = get_post($post_id);
	$rewritecode = array(
		$leavename? '' : '%postname%',
		$leavename? '' : '%pagename%',

	if ( '' != $permalink && !in_array($post->post_status, array('draft', 'pending', 'auto-draft')) ) {
		$unixtime = strtotime($post->post_date);
		$category = '';
		if ( strpos($permalink, '%category%') !== false ) {
			$cats = get_the_category($post->ID);
			if ( $cats ) {
				usort($cats, '_usort_terms_by_ID'); // order by ID
				$category = $cats[0]->slug;
				if ( $parent = $cats[0]->parent )
					$category = get_category_parents($parent, false, '/', true) . $category;
			// show default category in permalinks, without
			// having to assign it explicitly
			if ( empty($category) ) {
				$default_category = get_category( get_option( 'default_category' ) );
				$category = is_wp_error( $default_category ) ? '' : $default_category->slug;
		$author = '';
		if ( strpos($permalink, '%author%') !== false ) {
			$authordata = get_userdata($post->post_author);
			$author = $authordata->user_nicename;
		$date = explode(" ",date('Y m d H i s', $unixtime));
		$rewritereplace =
		$permalink = str_replace($rewritecode, $rewritereplace, $permalink);
	} else { // if they're not using the fancy permalink option
	return $permalink;

We Are Done

Once we translate the additional permalink tags, our gallery permalinks will look like this –

And just like that – we are done!

Permalink Conflicts

A common issue that arises when you create your own permalinks are permalink conflicts.

Permalink conflicts occur when two permalinks share the same regular expression structure.

Note – it is regular expression structure and NOT tag structure.

You can use tags with different and unique sounding names but it will not remove your conflict issue as long as your regular expression structure remains the same.

When permalink conflicts happen, you will usually get a 404 Page Not Found error. This happens because when the WordPress system goes to look for the proper permalink rule to fire, there are multiple ones that match. As a result, the system will only fire the first rule that it sees. Those objects that are tied to all subsequent but duplicate patterns will necessarily return a Page Not Found error because the system is using the wrong permalink rule.

The easiest way to avoid permalink conflict issues is to insert a unique slug into your structure. For example, instead of doing –


Do –


Adding the unique slug/keyword gallery into your permalink structure ensures that there are no regular expression pattern conflicts.

Is it possible to have multiple objects share the same permalink rule?

Yes, but this can get very messy. One way to do this is to only create a single permalink structure for all of your target objects. Then you must manually resolve which object you want by hooking into the request filter hook.

Related Articles

If you enjoyed this article, please help support our site.


  1. Maksim says

    Hi, I need help.
    I need url structure: http:/

    horoskoopit- just word
    kuukausihoroskooppi – post type name
    syyskuu – september on finish
    2015 – year

    so I create rewrite like this: $kuukausihoroskooppi_structure = ‘/horoskoopit/kuukausihoroskooppi/%monthnum%/%year%/%kuukausihoroskooppi%’;

    And I don`t need post_slug in url, but when I remove %kuukausihoroskooppi% from revrite, then this page open like archive.php

    And I need that month be not a number, it should be word so in $date I change code on: $date = explode(” “,date_i18n(‘Y F d H i s’, $unixtime));

    but then this page open like 404 page.

    What`s wrong and can I do url structure like:
    without slug of post and month with word?

  2. Andhi Irawan says

    Nice tutorial
    I have question, example I have a blog
    and product web
    In blog123 has post same name with productABC, like Gadget and Travel
    I want to create a link automatically in blog123.
    In blog123, for post Travel (, I create Show Product button link that link to
    I want that button link automatically via code something like http://productABC base url]/[title from blog123 post title or attribute or post permalink]

  3. Gerard says

    Is it possible to remove the slug of a custom post type? I would like to use them a lot but with the following URL structure: first the domain, then the postname, without the custom post type slug between the domain and the postname slug.

    Thanks in advance!

  4. Jos Faber says

    Thanks to this awesome post I’ve managed to create a complex rewrite structure with three different custom post types ( ~/brands/brand/model/type ).

    Thanks a gazillion!!

  5. says


    I’ve just used your code to add in the month and year into the permalink structure used for a custom post type that displays Events on my clients website. I’m a novice with functions and PHP, however this was really helpful and worked first time, I’m very happy.

    WordPress version: 3.8.1

    Thank you


  6. says

    Thank you for posting this series, it’s very thorough and the material is great!

    Can you post more information on multiple objects sharing the same rewrite rule? I need my permalink structure to be like the example you used without the unique prefix, like:


    The problem is that when I remove the unique prefix from your example code then all of my CPTs result in 404 errors. I would really appreciate more details on how to avoid this.

    Thank you again!

  7. Aryan says

    You are great. I was making a plugin for WP and I stucked in rewrite rule, I was searching for this tutorial since past 5 days. Thankyou for writing such amazing post.

  8. Ross says

    Your articles are some of the only good ones out there on this subject, thank you. Do you know how to create a custom permalink structure that will assign a random string of letters/numbers to each post? (For example, like — Maybe creating a structure that allows /%random% where %random% is an 8 character random string? You may be the only one who can help me on this!

  9. Marco Panichi says

    What if I’ve created a hierarchical custom type?

    The code suggested doesn’t work unfortunally!

    I can access posts only from /my-post and not from /my-parent-post/my-post

  10. says

    How can I create rules to display the custom post like my “standart posts, but add “.html” at the end of permalinks? I need a for only one CPT, so that others stay with the default setting.

  11. says

    Hi, i’m trying to remove the custom post type slug entirely. I’ve used this array but the slug keeps generating ‘rewrite’ => array(‘slug’=>”,’with_front’=>false), is this valid? I found it in the WP forums some said it worked others said it didn’t. How can I create custom posts so that no slug is generated? Thanks

  12. Espen says

    Hello, I’m trying to make a custom_post_type “review” and I want to add those to pages. I want to use pages as parents. I have managed to link up regular pages to the custom type. But the permalinks will not work. I only get 404.

    What I want is for the custom type to integrate with pages like regular posts:

    Default the permalinks are: but that gives me a 404 – and I don’t want that structure

    Only way to access the review is to type in this URL:

    That works, but I don’t want that either.

    Any tips? I’m close to pulling my hair out :)

  13. says

    Thank you Shibashake for this in-depth article.
    I managed to create working custom permalinks to CPT. The issue is that when rewrite set to false in the register_post_type function, than the archive page of the CPT is not being assigned a pretty url.
    i.e. I have cpt event and permalink for a single event may be /event/%year%/%monthnum%/%event% but the archive of all events valid only via and not with

    If setting the rewrite slug, then each single event post is losign the custom structure.
    How can these 2 can work together?


    • says


      I expect you’ve already found your solution, but I wanted to share how I handled the exact issue you’ve described. The code in this post was exactly what I needed to customize my site URL structure (thank you ShibaShake). However, I too, had 404’s on all of my previously working URL’s.

      To correct this, I added an additional permalink structure and made it unique enough to avoid conflicts. Using the example in this post, it would look something like this:

      $gallery_archive_structure = ‘/anything-unique/%post_type%/’;
      $wp_rewrite->add_rewrite_tag(“%post_type%”, ‘([^/]+)’, “post_type=”);
      $wp_rewrite->add_permastruct(‘post’, $gallery_archive_structure, false);

      In my instance, the links to the archive page(s) are hard-coded in the theme so there was no need to edit the WP generated archive link, but I suppose that’d be possible, too.

      Hope this helps the next person.

  14. says

    I had some problems with a code snippet I created from you example. At last I figured out that the date parameter was the cause of the problem. In your example it states date( ‘Y m d’ … ). I fixed my problem with date( ‘Y n j’ … )

    Hope that can help if someone else runs in to the same issue

  15. says

    Thanks so much for this in depth post. Really saved me on a bad permalink custom post type I had set up. I updated the permalink structure and they all broke. They are fixed now!

  16. says

    There was a question about showing cats and sub-cats in the url, like you can with regular wordpress categories. Of note here is when you register the taxonomy, there is a setting in the rewrite rules to do this.

    Under rewrite, the argument pair ‘hierarchical’ => true, turns on allowing /topic/sub-topic/super-sub-topic/, based on your structure, in the example called topic.

    register_taxonomy('topic', 'gam_qa',
    'labels' => array(
    'name' => _x( 'Topics', 'taxonomy general name' ),
    'singular_name' => _x( 'Topic', 'taxonomy singular name' ),
    'search_items' => __( 'Search Topics' ),
    'all_items' => __( 'All Topics' ),
    'parent_item' => __( 'Parent Topic' ),
    'parent_item_colon' => __( 'Parent Topic:' ),
    'edit_item' => __( 'Edit Topic' ),
    'update_item' => __( 'Update Topic' ),
    'add_new_item' => __( 'Add New Topic' ),
    'new_item_name' => __( 'New Topic Name' ),
    'menu_name' => __( 'Topics' ),
    'public' => true,
    'show_ui' => true,
    'hierarchical' => true,
    'query_var' => true,
    'rewrite' => array( 'slug' => 'q-and-a/topic', 'with_front' => true, 'hierarchical' => true ),
    'capabilities' => array(
    'manage_terms' => 'manage_qa_terms',
    'edit_terms' => 'edit_qa_terms',
    'delete_terms' => 'delete_qa_terms',
    'assign_terms' => 'assign_qa_terms'

    Then the function you call from. This is a stripped down version, using only the %topic% tag, which will be the name of your custom taxonomy.

    The code looks for a parent to the topic, and as long as it finds one, adds it to the url.

    function gam_qa_permalinks($permalink, $post_id, $leavename) {

    $post = get_post($post_id);
    $rewrite_code = array(

    if ( '' != $permalink && !in_array($post->post_status, array('draft', 'pending', 'auto-draft')) ) {

    if ( strpos($permalink, '%topic%') !== false ) {
    $terms = wp_get_object_terms($post->ID, 'topic');
    if (!is_wp_error($terms) && !empty($terms) && is_object($terms[0])) {
    $topics[] = $terms[0]->slug;

    $parent = $terms[0]->parent;
    while($parent) {
    $term = get_term($parent, 'topic');
    $parent = $term->parent;
    $topics[] = $term->slug;
    $topics = array_reverse($topics);

    $taxonomy_slug = join('/', $topics);
    $taxonomy_slug = 'no-topic';
    $taxonomy_slug = '';

    $rewrite_replace =
    $permalink = str_replace($rewrite_code, $rewrite_replace, $permalink);
    } else { // if they're not using the fancy permalink option
    return $permalink;

  17. says

    You just saved my sanity. I’ve been fighting with these dang ole permalinks/pagination issues for the last week straight.

    Great stuff, keep it up and thanks!

  18. Amy says

    Very basic error, not sure if I’m being silly. I’ve put the ‘// Add filter to plugin init function’ at the top of functions and then am using a custom post type called features, followed all your steps above.

    I want my structure to be


    but I’m just getting a 404 error?

    add_action('init', 'feature_register');

    function feature_register() {

    $labels = array(
    'name' => _x('Feature', 'post type general name'),
    'singular_name' => _x('Feature', 'post type singular name'),
    'add_new' => _x('Add New', 'Feature item'),
    'add_new_item' => __('Add New Feature'),
    'edit_item' => __('Edit Feature Item'),
    'new_item' => __('New Feature Item'),
    'view_item' => __('View Feature Item'),
    'search_items' => __('Search Feature'),
    'not_found' => __('Nothing found'),
    'not_found_in_trash' => __('Nothing found in Trash'),
    'parent_item_colon' => ''

    $args = array(
    'labels' => $labels,
    'public' => true,
    'publicly_queryable' => true,
    'show_ui' => true,
    'query_var' => true,
    'rewrite' => false,
    'capability_type' => 'post',
    'hierarchical' => false,
    'has_archive' => true,
    'menu_position' => null,
    'supports' => array('title','editor','thumbnail', 'comments','trackbacks', 'author'),
    'taxonomies' => array('post_tag'),

    register_post_type( 'feature' , $args );

    // add to our plugin init function
    global $wp_rewrite;
    $feature_structure = '/features/%year%/%monthnum%/%day%/%postname%';
    $wp_rewrite->add_rewrite_tag("%feature%", '([^/]+)', "feature=");
    $wp_rewrite->add_permastruct('feature', $feature_structure, false);

    Any help appreciated, thanks

  19. Amanda says

    Thanks for the info! It worked great to change the permalinks on my custom post type, but I am getting a 404 when I try to view the post? Is there something I’m missing? I’ve tried saving the Permalinks Settings Page, but that hasn’t done anything. Thanks in advance!

    • Amanda says

      Sorry, I wrote too soon! I saw you already answered it in the previous comments and that worked for me too. Thanks again for the great info!

  20. Rafal Jaskolski says

    Hi :)

    great thanks for this tutorial. It works for me, but….

    when I set rewrite as “%category%” im my post custom type there is conflict with pemalink for standard post.

    How can I solve this?

  21. says

    Hello there, thanks for your job, I have set a permalink structure for my custom type ‘spartiti’ in this way:
    but I would like to have my archive for this custom post type in this way:


    Is this possible?
    Thank you

  22. says

    Works great, thanks a billion!!! I modified it slightly for a custom post that I wanted to display like /books/%post_id%/%postname% so I was able to remove much of the code, and it looks like this:

    function BookPermalink( $permalink, $post_id, $leavename )
    $post = get_post( $post_id );

    // Don't rewrite unless it's published
    if ( '' != $permalink && !in_array( $post->post_status, array('draft', 'pending', 'auto-draft') ) )

    // These are the things we'll look for
    $rewrite_old = array(
    $leavename? '' : '%pagename%',
    $leavename? '' : '%postname%'

    // And here we decide what to replace them with
    $rewrite_new = array(

    // Now do the replacing
    $permalink = str_replace($rewrite_old, $rewrite_new, $permalink);


    return $permalink;

  23. Steven says


    I am having problems with creating this for two CPT,
    $wp_rewrite->add_permastruct(‘event’, $event_structure, false);
    $wp_rewrite->add_permastruct(‘place’, $place_structure, false);

    They seem to cancel each other out, if i comment one out the other will work but not both, do u have any advice?


  24. says

    Hey Shibashake, thanks for the awesome post on a topic I can’t find much info on anywhere else. If you’re still checking this post, could you help? I’m having trouble implementing this, as so:

    add_action('init', 'videos_rewrite');

    function videos_rewrite() {
    global $wp_rewrite;
    $wp_rewrite->add_permastruct('videos', '/videos/%year%/%monthnum%/%postname%', false);


    Along with your post_type_link hook. The permalinks change correctly, but all head to 404 pages. Am I doing something wrong? I know the structure is to be slightly different from your own.

    Thanks in advance.

      • says

        Thanks for getting back to me. I’ve attempted:

        function videos_rewrite() {
        global $wp_rewrite;

        $wp_rewrite->add_rewrite_tag("%videos%", '([^/]+)', "p=");
        $wp_rewrite->add_permastruct('videos', '/videos/%year%/%monthnum%/%videos%', false);


        (note the p= rather than videos= as my non-fancy permalinks are rather than how you describe. This may be where I’m going wrong?)

        Now that I’ve refreshed permalinks the page redirects to monthly archives, so is actually displaying what is located at Quite frustrating! Any thoughts on my problems, greatly appreciated!

        • says

          Yes p= expects the post id whereas your %videos% rewrite tag is passing it the post name (e.g. video-title) instead. I would suggest using a regular query argument (e.g. videos) rather than ‘p’ since p is the wordpress standard for post id.

Leave a Reply

Your email address will not be published.